# Yunke — external acceptance and release pack

Part of the [AI Voice Agent](/docs/modules_handbook/shared/voice-agent/readMe.md).
Prepared 2026-10-25. Writing this pack approves or executes none of its live steps.
All runtime Yunke gates remain off. No push or deployment occurred.

## What it does

Defines owner/vendor decisions, controlled acceptance, release and stop procedures after
offline engineering. Final related verification passes **491 PHP tests / 5880 assertions**
and **15 frontend tests**. PHP outbound traffic was denied except local test MySQL;
frontend outbound traffic was denied entirely. One existing PHPUnit XML deprecation
remains. Synthetic providers/storage do not prove customer calls, vendor rights or delivery.

The earlier one-number S2 approval was consumed. C1/S2 are limited historical evidence;
neither authorizes another call or replaces real acceptance. See the
[ledger](/docs/modules_handbook/shared/voice-agent/yunke-pdf-progress.md) and
[offline acceptance](/docs/modules_handbook/shared/voice-agent/yunke-pdf-acceptance.md).

Earlier 14:00 [owner test](/docs/modules_handbook/shared/voice-agent/yunke-owner-acceptance.md):
one task was accepted and automatically dialed, but a temporary harness error interrupted
the first attempt. The owner manually supplemented it; incomplete cloud results stayed
held. This is not full automatic acceptance. That separate one-test permission is now
consumed, and all standing runtime gates remain off.

The existing-call recovery later restored recording metadata, summary and native medium
intent without another dial; its original transcript offsets and complete terminal fields
remain unavailable. The Web mapper's verified medium normalization and the next isolated
test's safe post-call wait have new offline checks; neither is another live acceptance.

The latest 21:58 owner sample adds real two-way evidence: one task/dial, 156723 ms,
19 original turns (10 agent/9 customer), matching summary and high intent. The old
mapper held new hangup type 2; its phone monitor ended within twenty minutes. A narrow
offline correction passed 23 tests/526 assertions; corrected same-call real API collection
after that monitor closed returned applied then duplicate with no additional task/dial.
Do not present this as an uninterrupted corrected-version trial. Original final end
offset exceeds duration by 27655 ms and remains flagged. Background stability, formal
webinar content, business effects, media copies, deployment and pilot remain pending.
See the latest owner record for the full boundaries; this permission is consumed.

Offline follow-through now verifies one comment/mock high-intent notice/follow-up on
replay of the verified high-tag contract. Native timing semantics also reproduce all
19 source ends; the overrun is displayed as a fixed management warning. Precise word/audio
alignment was not an original PDF capability requirement, so it is not a new prerequisite
for accepting text transfer. Preserve the qualification and assess speech accuracy during
approved recording/pilot review. See [timing semantics](/docs/modules_handbook/shared/voice-agent/yunke-transcript-timing.md).

The next authorized live stage should exercise an approved registration/funnel business
scenario on a frozen corrected version, with exact content and test destinations named.
It can also supply uninterrupted-version evidence without a separate alignment-only call.
Real delivery, audio storage/playback, device stability, deployment and pilot still need
their stated approval/evidence; mock transports cannot complete those stages.

## How it works

### 1. Resolve the route before enabling it

| Requirement | Revised PDF | Implemented candidate | Remaining decision/evidence |
| --- | --- | --- | --- |
| Submit lead | Official import into a standing scheduled task | One new single-recipient App task per local attempt | Owner confirmed API-use permission and self-development; review production limits and change responsibility without waiting for the different standing-task API |
| Receive result | Official callback/webhook; avoid backend scraping | Existing Web Cookie, bounded queries, explicit task/child/action binding | Supported service identity, session renewal, polling limits and retention |
| Prompt/voice | Cloud configuration | Cloud configuration; no unverified local Retell prompt/dynamic-variable override | Approve the exact cloud agent, opening, knowledge and variable behavior |
| Stop/retry | Platform rules plus remote queue control | Platform guards; accepted/unknown tasks remain held | Prove remote stop/expiry, terminal outcomes and hidden retries |

The owner subsequently confirmed Yunke technical staff permit App/Web API use, with
petaV3 responsible for development. API-use permission and waiting for vendor development
are no longer blockers. The 17:27 bounded test passed automatic task submission, native
upload/analysis, explicit binding, isolated settlement and duplicate collection. The owner
answered without speaking, so its agent-only transcript is expected; customer speech and
meaningful intent were not exercised. No official import/webhook format was invented;
that original architecture is different from the implemented route. Service pricing and
production support still require their ordinary review. AutoX remains conditional on separate
written vendor permission and owner approval; it is not part of this implementation.

**Route status, stated plainly (2026-10-27).** petaV3 is integrated with Yunke over HTTP
APIs: task creation calls the App endpoint `aiCallOut/save`
(`YunkeAppTaskAdapter::CREATE_URL`, sent by `YunkeAppTaskSubmit`), and results are read
from the Web endpoints `taskPage`, `taskDetailPage` and `callDetail` (`YunkeWebReadClient`),
all inside petaV3 — no ADB, no simulated taps. The route in use is one new single-recipient
App task per local attempt, existing Web session queries pulled by the bounded watch, and
explicit taskId → subTaskId → callActionId binding with duplicate protection. What is NOT
implemented is the PDF's other route — importing leads into a standing scheduled task and
receiving results by an official callback — for which no endpoint or import format exists.
That is a route choice, not an absence of API integration. Protocol knowledge comes from
App 2.0.20 / Web research; permission to use the existing APIs is the owner's report of the
vendor's technical staff, with charges and scope not documented here. Production deployment,
the formal pilot and the master merge are release decisions, listed separately in §5.

### 2. Prerequisite record

For each item record approver, date and private evidence reference; blank means pending.
Never put credentials, full phone numbers, signed audio URLs or transcripts in Git.

| Item | Responsible party | Evidence needed before its live stage |
| --- | --- | --- |
| Route/commercial terms | Wai Kit / Lee Jie and vendor | App/Web use is owner-confirmed as allowed; review annual/minute/API/export charges, limits and change responsibility before production |
| Hardware/market | Operator and vendor | Exact handset/OS/region/hardware revision and USB/Bluetooth route, supported-model list/manual, local SIM, cap/window |
| Background stability | Operator | Approved lock-screen, charging, background, reconnect and remote-stop trials; owner records update/battery/autostart settings rather than this pack changing them |
| Identity | Vendor and maintainer | Exact company/user across writer/reader; phone-safe authentication and expiry/recovery. A fresh App login invalidated the phone; short Web coexistence does not prove renewal |
| MY/HK expansion | Owner and vendor | Independent phone/SIM/market mapping and session entitlement; do not assume two phones can share an App identity without eviction |
| Contact/conversion | Business owner | Current consent/contact policy and DNC/block list; same-funnel confirmed-won coverage and exclusion of legacy/untracked conversions |
| Content/voice/privacy | Wai Kit and responsible reviewers | Approved bilingual script/Q&A and AI disclosure, actual written clone consent, processors/hosting/transfers, privacy notice, retention/export/deletion. PDF claims are not verified consent or legal clearance |
| Operations | Release owner | Isolated acceptance environment, durable asynchronous queue, shared atomic-lock cache, scheduler, failure review and private credential provisioning |

Missing vendor samples: confirmed no-answer/busy/voicemail/failure/rejection; intent levels
with meanings; a spoken do-not-contact request; multi-attempt IDs; cancellation/expiry;
incoming callbacks. Obtain redacted raw responses with explicit parent/child/action IDs,
timestamps, turn roles and expected meaning. Supported completed-call samples do not
establish these enums. Unsupported/conflicting/unassociated rows stay held. Platform DNC
is enforced; automatic extraction of a spoken opt-out still needs verified evidence and
review. Do not guess a label's intent, retry or DNC meaning.

### 3. Gate plan — actual values all OFF

| Gate | Purpose | Future acceptance boundary |
| --- | --- | --- |
| `YUNKE_APP_WRITE_ENABLED` | New single-task submissions | One approved owner number; exact nonempty `YUNKE_APP_WRITE_ALLOWED_NUMBERS`, token/company/user and paused profile reviewed first |
| `YUNKE_WEB_READ_ENABLED` | Existing Web Cookie metadata/transcript reads | Approved scope and matching company/user; auth errors stop, never become empty results |
| `YUNKE_APP_RESULTS_ENABLED` | Shared App/Web processing | Isolated acceptance DB only after approval; no production write or disposable PHPUnit DB |
| `YUNKE_WATCH_ENABLED` | Periodic collection | Also requires Web-read and result gates; at most 20 bindings/run, no account-wide backfill |
| `YUNKE_APP_AFTERMATH_ENABLED` | Comments/follow-up/redial effects | Off for initial self-test; isolated effects and actual recipients/delivery need separate approval |
| `YUNKE_WATCH_ALERTS_ENABLED` | Internal review notice | Separate destination/subscription approval; silence is not a device-outage diagnosis |
| `YUNKE_RECORDING_COPY_ENABLED` | Real audio fetch/private copy | Explicit download/storage/playback approval and verified exact CDN allowlist; empty allowlist refuses all |
| `YUNKE_APP_READ_ENABLED` | App-session reader/login | Keep off; never refresh via a new App login or fall back from Web authentication |

Profile status, split, consent, cap and window are additional controls. Local log-only
behavior still requires `VOICE_REAL_IN_LOCAL` for real voice. Tests changed gates only
in memory. A release must verify effective cached config and **all workers' code/config
versions** without printing secrets. Editing `.env` does not stop an in-flight worker
or a task already accepted by the phone.

### 4. Newly approved owner-number acceptance

Proposed reviewable scope; do not execute now:

1. Name approver/operator, release/tree, isolated DB/storage/queue, one owner-controlled
   `<OWNER_E164>`, phone/identity, timezone, window and cloud content version. Verify the
   handset is authenticated and idle. Owner chooses recipient screening/voicemail settings;
   previous iPhone screening affected audio observations.
2. Approve **one task, one recipient, at most one dial**, maximum 20-minute observation
   and a proven phone-side stop procedure. Exclude other tasks/recipients. If creation,
   authentication or stop state is unclear, stop and preserve evidence; no creation retry
   or Retell fallback. Preparation approval is not permission to dial.
3. Keep customer/team messages, aftermath and recording copies off. Provision only the
   exact approved existing token/Cookie scope without a new App login. Do not depend on
   a broad production scheduler or production follow-up queue for this test.
4. Invoke the reviewed platform placement seam in the isolated environment. Capture local
   UUID, committed claim and one schedule. A literal parent taskId means acceptance, not
   dialing or a per-call ID. Preserve CREATE_UNKNOWN without replacement on uncertainty.
5. On first observed dial, stop further work using the approved procedure. Verify the
   phone returns idle and record the remote state; a rejected pause is not cancellation
   proof. Record two-way AI audio, start/end, result and whether screening occurred.
   Keep a confirmed-paused executor alive for native post-call upload/analysis rather
   than force-stopping after a fixed 45-second grace. Normal stop follows verified
   settlement/analysis and duplicate checks. At the absolute approved deadline or an
   unsafe state, stop as authorized and preserve incompleteness without a replacement.
6. With separate read/isolated-ingestion approval, verify a result row's taskId,
   subTaskId and callActionId/call ID. Detail lacks reliable ID echoes; request context
   cannot repair contradictory rows. Bind explicit IDs, never guess by phone/time. Read
   transcript/summary/raw intent as metadata without GETting any audio URL.
7. Check one settlement, turns and first late analysis; duplicate collection must not
   replace identity, duplicate turns/effects or clear holds. Validate real mapper semantics.
   S2's unclassified raw intent does not prove high/medium support. Later recovered
   medium facts support only the explicitly verified matching label/tag combination;
   the later verified high combination has native and offline follow-through evidence.
   Non-answer/opt-out outcomes and actual delivery still need bounded real evidence.
8. Disable/locally pause test work, safely apply config and verify phone queue/idle state.
   Retain a private sanitized receipt. Do not backfill production.

`voice-agent:test-call` is Retell-specific: do not use it for Yunke. There is no general
Yunke live-test CLI. A maintainer must review the exact isolated harness/parameters before
approval. Never improvise a command that boots the developer `.env` with real credentials.

Miss/intent/DNC/three-attempt, background/reconnect and session-expiry tests each need
their own bounded owner-number scope. One success cannot validate them. Recording
acceptance separately proves real CDN/TLS, private storage, fresh signed playback, expiry,
failure quarantine and approved retention/deletion. Playback uses two temporary stages,
each with 1–15 minute TTL; disabling copy does not revoke links already issued.

### 5. Approved deployment and pilot

Only the release owner may push/merge/deploy. Review the task range against the actual
production baseline, migrations and backup. Local dev-chen is not a deployed release.
Do not run migrations/Artisan against the real developer environment as an offline check.
Initial installation leaves all Yunke gates off, phone profiles paused and new split absent.

Follow existing [Horizon](/docs/modules_handbook/production-setup/horizon.md) and
[scheduler](/docs/modules_handbook/production-setup/scheduler.md) runbooks. Verify
`QUEUE_DRIVER=redis` rather than sync, required workers, one scheduler, shared locks and
compatible timeouts; build assets, apply reviewed schema/config and restart long-running
workers with the release procedure. Verify disabled state before enabling anything.
Never retry all failed jobs to recover one uncertain Yunke attempt.

Before a customer pilot approve the route, live semantics, cohort, message destinations
and stop operator. Use one funnel, 50/50 fixed arms, equivalent cloud/Retell content and
verified `intent_level` extraction; 10:00–21:00 local windows, conservative profile caps,
**three total attempts / 120-minute gap** for supported confirmed misses. A profile cap
is not a verified shared-SIM limit. Review registration, 1440-minute reminder and 30-minute
live no-show triggers against actual attendance, consent, DNC and confirmed-won records.

The PDF medium-intent flow currently reuses the customer-spoke thanks/WhatsApp path;
this is not a tested vendor medium-only rule. Owner must accept that behavior/content or
revise it before rollout. High intent needs verified standard mapping and a customer turn.
Approve lead-visibility-qualified Telegram subscriptions and a named human responsible
for following up within 24 hours. Final missed WhatsApp needs supported confirmed outcomes,
not an elapsed task timeout.

Where feasible observe 50+ calls/arm; the PDF's 10–20 is exploratory. After approved
recording access, owner reviews five calls daily: mixed Chinese/English/Cantonese accents,
understanding, interruption, latency, relevance, disclosure and false facts. Log versions
and approvers for weekly Q&A/prompt updates. Agree quality/latency/stop thresholds before
viewing results; this pack invents no pass targets. Human comparison is entered manually.

Use the report's assigned/rang denominators, actual providers/crossover, transcript/intent
missingness, attendance, cost and wait coverage. Add recognition, response latency,
registration and daily review observations manually. Compare real Yunke invoices plus
allocated annual/hardware/phone/SIM costs with Retell **and Twilio** charges. PDF prices
are estimates; unknown is not zero/free. Local-row-to-start wait is not proven official
import latency. Owner records Phase 3 expand/stop decision and reasons; no data or decision
was fabricated here.

### 6. Stop and rollback drill

1. Approved operator stops the **phone executor/remote work** with a proven procedure and
   verifies known/unknown outstanding tasks. Local pause/DNC, an ended schedule or a closed
   App window is not by itself proof that the remote queue stopped.
2. Disable new submissions, locally pause the profile and stop new variant admission;
   safely refresh worker/config snapshots. Review accepted/unknown and assigned work before
   placing replacement calls through any provider.
3. Routing `--no-split` affects future admission. Existing assignments retain their arm;
   it neither cancels cloud tasks nor moves queued Yunke leads to Retell. No automatic
   fallback may call a person while remote outcome is uncertain.
4. Drain results only under separately approved identity/data scope. Aftermath, alerts
   and copies remain independent. Auth failure stops reading. Do not close held tasks as
   misses by age, clear IDs or replay creation; copy leases are not call timeouts.
5. Preserve bindings, decisions, failures and private evidence. Resolve remote queue/contact
   restrictions before owner reopens Retell admission. Code/schema rollback needs the
   release owner's plan; do not delete evidence or blindly reverse migrations.

Include existing limits in pilot review: a lost redial job has no dedicated sweep; a
Retell concurrency refusal during redial releases the held miss; effects do not promise
exactly-once delivery. Monitor the durable queue and review scoped failures without
recreating an uncertain remote attempt.

## Reference usage

Existing commands for a separately approved environment, not instructions to run now.
Profile creation writes that DB; routing changes can admit calls. Replace placeholders
and review effective gates first.

```sh
php artisan voice-agent:yunke-profile '<PAUSED_PROFILE_NAME>' --prefix=60 --cap='<APPROVED_CAP>' --window=10:00-21:00
php artisan voice-agent:routing '<CONTROL_SLUG>'
php artisan voice-agent:pilot-report '<CONTROL_SLUG>' --from='<YYYY-MM-DD>' --to='<YYYY-MM-DD>'
```

Provisioning creates a paused platform App profile, not an agency credential or vendor
task. No command here enables a gate or starts a pilot. Future approved routing changes
use the [routing reference](/docs/modules_handbook/shared/voice-agent/pilot-routing.md);
clearing a split is not a remote emergency stop.

## Related files

- [Progress](/docs/modules_handbook/shared/voice-agent/yunke-pdf-progress.md), [offline acceptance](/docs/modules_handbook/shared/voice-agent/yunke-pdf-acceptance.md) — scope/evidence.
- [App caller](/docs/modules_handbook/shared/voice-agent/yunke-app-caller.md), [Web results](/docs/modules_handbook/shared/voice-agent/yunke-web-results.md), [watch](/docs/modules_handbook/shared/voice-agent/yunke-watch.md) — submission/binding/session limits.
- [Profiles](/docs/modules_handbook/shared/voice-agent/yunke-profiles.md), [pilot routing](/docs/modules_handbook/shared/voice-agent/pilot-routing.md) — provisioning, assignment, retry/report.
- [Recording copies](/docs/modules_handbook/shared/voice-agent/yunke-recordings.md), [Media](/docs/modules_handbook/shared/media/readMe.md) — private retention/playback/cleanup.
- `config/services.php`, `.env.example`, `app/Console/Kernel.php` — default-off controls and scheduled watch.
