# WO-02: Deliver main-agent progress explanations in Telegram tasks

Status: complete — integrated and verified offline, with baseline failures recorded below

## Anchors

- `packages/orchestrator/prompts/agentic/system-common.md`: progress instruction.
- `packages/cli/src/tui/interactive.ts`: the main model's content stream is
  buffered at `stream_token` and spoken at `stream_end` in chat/verbose mode.
- `packages/cli/src/tui/voice.ts`: `describeToolCall`/`describeToolResult` are
  rule-based action narration; they are not a second explanation model.
- `packages/cli/src/tui/telegram-bridge.ts`: action response contract,
  `telegram_progress`, admin panel, public activity, runner callback.
- `packages/cli/src/tui/telegram-public-activity.ts`: shared activity renderer.

## Acceptance

- [x] Admin DMs and public groups can emit useful explanations before material
  work and at milestones, using the main model without extra narration inference.
- [x] Action instructions distinguish user-facing progress from the final reply.
- [x] Admin Reply prioritizes current explanation over the repeated request.
- [x] Public activity refreshes preserve model-authored progress.
- [x] Progress stays separate from final candidates and completion accounting,
  including a response mixing progress and substantive tool calls.
- [x] Delayed/coalesced updates eventually flush, with no stale-owner or
  post-cancellation sends and no duplicate final answer.
- [x] Production-path tests cover DM/group delivery, ownership, ordering,
  sanitization, final separation, and existing typing behavior.

## Implementation and verification

The live task's retained main-model turns contained only tool calls. Merely
forwarding the existing content stream would therefore leave this task silent.
The action contract now instructs the existing main agent to call the existing
`telegram_progress` mechanism before substantial work and at useful milestones.
It is available to authenticated private admins as well as already-authorized
groups. The text is explicit progress, not an arbitrary final-answer stream;
there is no separate narration inference. Simple immediate answers need no
progress call.

Admin Reply shows this progress instead of repeating the original request.
The request and adopted/pending instruction facts remain in private Activity.
Group narration is persisted on the owned activity record and composed by the
same renderer as tool activity, including later refreshes and navigation.
The progress tool has no completion or delivery authority. The paired
orchestrator repair classifies prose accompanying any registered progress tool
as progress even in a mixed substantive-tool response; `task_complete` remains
the explicit final boundary. The actual runner regression checks that real
file work proceeds and progress never becomes a final candidate or ledger
evidence.

Admin panel writes now share one coalescing writer with a trailing flush.
Ownership is checked again at provider dispatch; Stop, epoch/generation change,
replaced worker, admin/bot change, and finalization reject pending progress.
An adopted private continuation retains its latest update through a throttle
or in-flight transport wait. It receives a new archive identity; subsequent
ordinary, deduplicated-tool, and typed checklist events use the current binding,
leaving the prior input's archive unchanged. An update recorded while Activity
is selected does not claim that the Reply narration was visibly delivered.

Both primary and nested native Telegram runner callbacks now suppress
telemetry-only status text from raw sub-agent output. The primary typed event
and durable private Activity archive retain the diagnostic. Ordinary progress
and current errors remain observable. These two consumers complete the WO-01
visibility contract on the Telegram path.

The acquisition prompt recognizes the WO-04 `download`/`downloads` browser
artifact handoff and requires verification of the saved file. Admin desktop
guidance discovers existing controls with `tool_search('desktop')`, observes
the actual desktop before acting on a native chooser, and uses the existing
`vision_action_loop` text/key fields. Public desktop capability is unchanged.
The browser constructor receives the task `repoRoot` as `workingDir`.

Verification on 2026-10-11 used mocked inference/Telegram and isolated local
fixtures. No live inference, Telegram sends, service changes, or original
worktree edits were performed. `pnpm exec tsc --noEmit` and `git diff --check`
passed. The native SQLite dependency was rebuilt in the isolated dependency
installation before running the actual native-runner tests.

The final 11-file run in `/tmp/omnius-narration-final-tests.log` has 182 passing
tests, two pre-existing typing fixture failures and their unhandled rejection.
These ten suites pass all 169 tests:

| CLI test file | Passed |
| --- | ---: |
| `telegram-admin-progress.test.ts` | 17 |
| `telegram-admin-live-panel.test.ts` | 13 |
| `telegram-private-native-core.test.ts` | 10 |
| `telegram-private-native-runner.test.ts` | 24 |
| `telegram-progress-message.test.ts` | 36 |
| `telegram-public-activity.test.ts` | 30 |
| `telegram-run-activity.test.ts` | 9 |
| `native-inprocess-agent.test.ts` | 14 |
| `telegram-typing-owner-handoff.test.ts` | 2 |
| `telegram-private-native-steering.test.ts` | 14 |

The three assessment-baseline `EISDIR` failures are fixed by filtering ledger
enumeration to files in `telegram-progress-message.test.ts` and
`telegram-public-activity.test.ts`; their original delivery assertions remain.

Known baseline failures outside this repair:

- `telegram-intake-presentation.test.ts`: all eight failures reproduce on the
  unchanged baseline CLI implementation (`f1b2d5f9`, documentation descendant
  `ddaaf332`) before WO-02 integration. The case “runs fresh input once without
  inheriting an unrelated open-task contract” rejects with “Native requirement
  input is unavailable or does not own this actor/topic.” The seven “separates
  request comprehension from routing diagnostics” cases time out at 5000 ms:
  unavailable router; valid route without an outcome; validated explicit
  outcome; malformed outcome without validation receipt; unbound retained
  outcome; retained outcome with another receipt; retained outcome from another
  input. Reproduction log: `/tmp/omnius-intake-baseline-tests.log`.
- `telegram-typing-action-handoff.test.ts`: 13 pass; two failures and one
  unhandled rejection reproduce at integration `70efc6b2` before WO-02.
  “keeps one lease through the real quick handler, delayed action planning, and
  worker adoption” expects one `runTelegramChatCompletion` call but receives
  zero. Its missing public attention grant produces “Public native work requires
  an issued exact-input public attention grant.” “keeps terse human liveness
  through an actual typed 503 broker retry without granting a visible reply”
  expects two `telegram_joint_intake` schemas followed by
  `telegram_joint_intake_review`, but receives three
  `telegram_attention_reconciliation` schemas. Reproduction log:
  `/tmp/omnius-typing-handoff-baseline-tests.log`.

This is offline implementation verification. Live model adoption of the new
progress instruction and provider behavior have not been tested in the active
Telegram session. WO-05 owns integrated delivery and the baseline-failure report.
