Add a natural TUI surface for broker and dispatch logs

coilyco-ops commented

2026-07-10 02:09:16 +00:00

Owner

Kai hit a usability gap while working from a TUI: there is no natural way to view broker logs from the director/read-only surface.

Current shape:

ward agent logs <ref> reads one engineer run's logs through the dispatch broker or host archive.
Broker-forwarded dispatch failures print a host path like ~/.ward/agent-logs/dispatch/<stamp>.log or /Users/kai/.ward/....
From a TUI inside a warded director surface, that path is not naturally readable. The operator has to leave the surface, know where host logs live, and manually inspect them.
docs/broker.md documents WARD_BROKER_LOG for the in-container credential broker, but there is no command-shaped read surface for broker logs. docs/agent-logs.md covers engineer logs only.

Scope:

Add a first-class command to read broker/dispatch logs naturally from a TUI/director surface. Exact spelling can be chosen by implementation, but examples that fit the existing surface are:
- ward agent logs --dispatch <ref-or-latest>
- ward agent broker-logs --tail 200 --follow
- ward agent logs dispatch --latest
The command should work from a read-only director surface by forwarding through the existing dispatch broker, not by requiring a host filesystem path or Docker socket.
It should cover the logs that matter for blocked initialization and forwarded dispatch failures: dispatch wrapper logs under the host ~/.ward/agent-logs/dispatch/ tree, and any credential-broker log that ward intentionally exposes (WARD_BROKER_LOG) if that is available in the current execution model.
It should support at least --tail, source reporting, and an ergonomic "latest/recent" path so a TUI user can inspect the failure they just saw without copying a full host path.
Update docs/agent-logs.md, docs/broker.md, docs/troubleshooting.md, and docs/FEATURES.md as needed.

Acceptance:

A director/TUI user can run one ward command to view the broker/dispatch log for the most recent brokered launch failure.
The command reports which source it read and fails loudly when no broker log source exists.
Existing engineer-log behavior remains unchanged.
Tests cover the broker-forwarded read path and a latest/recent dispatch-log selection.

Context: this came up while debugging warded init failures where broker dispatch output only gave host log paths.

Kai hit a usability gap while working from a TUI: there is no natural way to view broker logs from the director/read-only surface. Current shape: * `ward agent logs <ref>` reads one engineer run's logs through the dispatch broker or host archive. * Broker-forwarded dispatch failures print a host path like `~/.ward/agent-logs/dispatch/<stamp>.log` or `/Users/kai/.ward/...`. * From a TUI inside a warded director surface, that path is not naturally readable. The operator has to leave the surface, know where host logs live, and manually inspect them. * `docs/broker.md` documents `WARD_BROKER_LOG` for the in-container credential broker, but there is no command-shaped read surface for broker logs. `docs/agent-logs.md` covers engineer logs only. Scope: * Add a first-class command to read broker/dispatch logs naturally from a TUI/director surface. Exact spelling can be chosen by implementation, but examples that fit the existing surface are: * `ward agent logs --dispatch <ref-or-latest>` * `ward agent broker-logs --tail 200 --follow` * `ward agent logs dispatch --latest` * The command should work from a read-only director surface by forwarding through the existing dispatch broker, not by requiring a host filesystem path or Docker socket. * It should cover the logs that matter for blocked initialization and forwarded dispatch failures: dispatch wrapper logs under the host `~/.ward/agent-logs/dispatch/` tree, and any credential-broker log that ward intentionally exposes (`WARD_BROKER_LOG`) if that is available in the current execution model. * It should support at least `--tail`, source reporting, and an ergonomic "latest/recent" path so a TUI user can inspect the failure they just saw without copying a full host path. * Update `docs/agent-logs.md`, `docs/broker.md`, `docs/troubleshooting.md`, and `docs/FEATURES.md` as needed. Acceptance: * A director/TUI user can run one ward command to view the broker/dispatch log for the most recent brokered launch failure. * The command reports which source it read and fails loudly when no broker log source exists. * Existing engineer-log behavior remains unchanged. * Tests cover the broker-forwarded read path and a latest/recent dispatch-log selection. Context: this came up while debugging warded init failures where broker dispatch output only gave host log paths.

coilyco-ops added the

labels

2026-07-10 02:09:23 +00:00

coilyco-ops referenced this issue

2026-07-10 02:17:24 +00:00

Remove runtime KDL/specgen dependency from ward core paths #929

coilyco-ops referenced this issue

2026-07-10 03:29:45 +00:00

Remove runtime KDL/specgen dependency from ward core paths #929

coilyco-ops added

and removed

labels

2026-07-10 09:00:33 +00:00

coilyco-ops commented

2026-07-10 09:01:52 +00:00

Author

Owner

Fresh director-surface repro from the 2026-07-10 usability sweep:

After redispatching ward#943, the issue had a fresh reservation comment (28996) but warded list no longer showed engineer-codex-ward-943. Trying to inspect it from the TUI/director surface was not useful:

ward agent logs: using docker logs engineer-codex-ward-943 --tail 120
825cb19fc46fafd925271da6254c852f34cbaf21

That output gives the chosen source and a container id, but no actual log lines and no explanation of whether the container exited, produced no logs, had no archive yet, or failed before the console stream was captured.

So the needed log surface is not only broker dispatch logs. It should also make this run state legible when an issue has a reservation, the container is not in warded list, and warded logs <issue> finds only an unhelpful container/archive source.

Fresh director-surface repro from the 2026-07-10 usability sweep: After redispatching `ward#943`, the issue had a fresh reservation comment (`28996`) but `warded list` no longer showed `engineer-codex-ward-943`. Trying to inspect it from the TUI/director surface was not useful: ```text ward agent logs: using docker logs engineer-codex-ward-943 --tail 120 825cb19fc46fafd925271da6254c852f34cbaf21 ``` That output gives the chosen source and a container id, but no actual log lines and no explanation of whether the container exited, produced no logs, had no archive yet, or failed before the console stream was captured. So the needed log surface is not only broker dispatch logs. It should also make this run state legible when an issue has a reservation, the container is not in `warded list`, and `warded logs <issue>` finds only an unhelpful container/archive source.

coilyco-ops commented

2026-07-10 09:01:57 +00:00

Author

Owner

WARD-RESERVATION: held 🔒

reservation details

Holder: container engineer-codex-ward-927 on host kais-macbook-pro-2.local.

Reserved by ward agent --harness codex (reserved 2026-07-10T09:01:56Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (1h TTL). --force overrides.

Do not comment on or edit this issue to steer the run while it is reserved. The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a new issue, dispatched fresh. That is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494).

run seed context — what this run is carrying (ward#609)

Resolved: coilyco-flight-deck/ward#927 · branch issue-927 · harness codex · workflow pull-requests-and-merge
Run: engineer-codex-ward-927 · ward v0.569.0 · dispatched 2026-07-10T09:01:56Z
Comment thread: 1 included in the pre-flight read, 0 stripped (ward's own automated comments).
- included: @coilyco-ops (2026-07-10T09:01:52Z)

Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.569.0).

— Codex, via ward agent

WARD-RESERVATION: held 🔒 <details><summary>reservation details</summary> Holder: container `engineer-codex-ward-927` on host `kais-macbook-pro-2.local`. Reserved by `ward agent --harness codex` (reserved 2026-07-10T09:01:56Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (1h TTL). `--force` overrides. **Do not comment on or edit this issue to steer the run while it is reserved.** The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a **new issue, dispatched fresh**. That is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494). <details><summary>run seed context — what this run is carrying (ward#609)</summary> - **Resolved:** `coilyco-flight-deck/ward#927` · branch `issue-927` · harness `codex` · workflow `pull-requests-and-merge` - **Run:** `engineer-codex-ward-927` · ward `v0.569.0` · dispatched `2026-07-10T09:01:56Z` - **Comment thread:** 1 included in the pre-flight read, 0 stripped (ward's own automated comments). - included: @coilyco-ops (2026-07-10T09:01:52Z) Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.569.0). </details> </details>  — Codex, via `ward agent`

coilyco-ops referenced this issue from a pull request that will close it,

2026-07-10 09:23:48 +00:00

feat: add broker logs surface #987

coilyco-ops commented

2026-07-10 09:25:16 +00:00

Author

Owner

WARD-OUTCOME: merge-ready

details

workflow: pull-requests-and-merge; review summary: skipped (review gate skipped by ~/.ward/config.yaml default)

felt: direct, with the new broker-log surface fitting the existing agent log plumbing cleanly.
confidence: high
surprises: none beyond the initial Forgejo config-source warning in this container.
follow-ups: director merge can land once the issue thread is ready for the merge lane.

WARD-OUTCOME: merge-ready <details><summary>details</summary> workflow: pull-requests-and-merge; review summary: skipped (review gate skipped by ~/.ward/config.yaml default) felt: direct, with the new broker-log surface fitting the existing agent log plumbing cleanly. confidence: high surprises: none beyond the initial Forgejo config-source warning in this container. follow-ups: director merge can land once the issue thread is ready for the merge lane. </details>

coilyco-ops referenced this issue

2026-07-13 03:27:08 +00:00

Reservation collision silently strands review-driven follow-up dispatches (ward#987 rotted 3 days) #1149

coilyco-ops referenced this issue

2026-07-13 03:58:39 +00:00

fix(agent): stop reservation collisions silently stranding review-driven redispatches #1163

coilyco-ops referenced this issue

2026-07-13 04:01:25 +00:00

Reservation collision silently strands review-driven follow-up dispatches (ward#987 rotted 3 days) #1149

coilyco-ops commented

2026-07-13 08:06:23 +00:00

Author

Owner

The burn-down session, working for Kai, re-checked this issue against current main and closes it as covered.

The acceptance criteria are satisfied on main:

A director/TUI user runs one command: ward agent logs <ref> falls back per-ref to the newest host dispatch wrapper log (latestDispatchLogPathForRef in cmd/ward/agent_logs.go), forwarded through the existing dispatch broker, with no host filesystem path or Docker socket required.
Forwarded-dispatch failures render a ready-to-run ward agent logs <ref> locator (cmd/ward/agent_dispatch_broker.go), so the operator inspects the failure they just saw without copying a full host path.
The command reports which source it read, and existing engineer-log behavior is unchanged.
Tests cover the broker-forwarded read path (cmd/ward/agent_dispatch_broker_test.go) and the dispatch-log fallback selection (cmd/ward/agent_logs_test.go).

PR #987 carried the original implementation, and the burn-down session closed it as superseded per the disposition recorded in ward#1149. The extras that PR carried beyond this issue's acceptance - a no-ref latest-dispatch selection, a WARD_BROKER_LOG credential-broker read surface, and file --follow - belong in a fresh issue against current main if still wanted.

The burn-down session, working for Kai, re-checked this issue against current main and closes it as covered. The acceptance criteria are satisfied on main: * A director/TUI user runs one command: `ward agent logs <ref>` falls back per-ref to the newest host dispatch wrapper log (`latestDispatchLogPathForRef` in `cmd/ward/agent_logs.go`), forwarded through the existing dispatch broker, with no host filesystem path or Docker socket required. * Forwarded-dispatch failures render a ready-to-run `ward agent logs <ref>` locator (`cmd/ward/agent_dispatch_broker.go`), so the operator inspects the failure they just saw without copying a full host path. * The command reports which source it read, and existing engineer-log behavior is unchanged. * Tests cover the broker-forwarded read path (`cmd/ward/agent_dispatch_broker_test.go`) and the dispatch-log fallback selection (`cmd/ward/agent_logs_test.go`). PR #987 carried the original implementation, and the burn-down session closed it as superseded per the disposition recorded in ward#1149. The extras that PR carried beyond this issue's acceptance - a no-ref latest-dispatch selection, a `WARD_BROKER_LOG` credential-broker read surface, and file `--follow` - belong in a fresh issue against current main if still wanted.

coilyco-ops closed this issue

2026-07-13 08:06:45 +00:00

Rows
Columns

Add a natural TUI surface for broker and dispatch logs #927