Check agent-work delivery readiness at launch and handoff #12

Summary

An app that queues agent work can still be handed to the user with no persistent delivery process running. The agent may test with bridge start --once or an interactive --foreground process, then finish with serve. The app remains healthy and accepts requests, but subsequent tasks stay unclaimed.

This issue covers delivery readiness at launch and handoff, after #21, #25 and #27. Those PRs make the problem visible and fix other queue/delivery failures; they do not ensure that a background bridge is left running.

Baseline after the three PRs

The PRs are stacked: #21 → #25 → #27.

• Enforce agent-state UX for app→agent features #21: agent-task UI, a waiting/no-listener hint, validation and walk-verify coverage, plus Windows harness spawning, headless Claude Code permissions and heartbeat fixes.
• fix: pocketbase kit #25: PocketBase queue support and the corresponding agent-task UI.
• fix: prevent starters from requeuing unfinished agent work #27: refuse requeueing while the record's current task is unfinished, preserving the original task and result.

Existing framework support should be reused:

• Plain agent-app <dir> bridge start already launches a detached background process.
• agent-app <dir> bridge already reports the local bridge, harness route and waiting tasks.
• agent-app list already displays a recorded bridge whose process is alive.
• The bridge loop already tolerates temporary app outages and continues polling.

The remaining gaps are that serve performs no bridge readiness check, a missing bridge is silent in list, stop does not explain the bridge's independent lifecycle, and creator/modify do not require a final delivery check on the live app.

Scope and decisions

1. Warn at launch; preserve the existing per-app opt-in behavior. serve will not silently start harness runs. A healthy server can still return success, but app health and delivery readiness must be reported separately.
2. Use the existing detached bridge for authorized handoffs. Creator/modify must leave and verify a background bridge when the feature needs it and app-triggered agent runs are authorized.
3. Report what is observable. No local bridge does not prove that no agent is listening: a harness may independently poll a2app ... tasks next --wait. Neither a discovered harness route nor a live PID alone proves successful delivery.
4. Keep bridge and app shutdown independent in this change. Report a bridge that remains running after stop; do not introduce implicit termination.
5. Defer OS startup and crash supervision. Reboot persistence and automatic respawning can follow separately. An already-running bridge should continue through an ordinary app stop/serve cycle.

Implementation plan

1. Share delivery inspection

Extract/reuse the existing bridge-record and queue-read logic so serve, list and bridge agree about:

• Whether app-owned code is known to queue agent work. Reuse Enforce agent-state UX for app→agent features #21's trigger scanner, including apps without a human View; do not infer this merely from an adapter supporting a queue.
• Whether a local bridge is absent, stale or has a live recorded process.
• Waiting work observed through the queue, or an explicit unknown/unavailable result when the read fails.

Keep inspection read-only and bounded. Verify app identity before interpreting queue data. Preserve existing JSON fields and add structured readiness information without changing the meaning of server health. Document static detection limits; observed waiting work must still be reported when no trigger was statically detected.

2. Check both successful serve paths

After a fresh healthy launch and an idempotent "already serving" result:

• For an app known to queue agent work with no live local bridge, print a prominent warning that delivery has not been verified and tasks may remain unclaimed.
• Include the executable command for that app: agent-app <dir> bridge start, plus agent-app <dir> bridge for diagnosis.
• Mention external polling as a valid delivery alternative.
• Report a running local bridge separately from app health. Do not claim its PID proves that the harness can complete work.
• Do not warn for ordinary apps with no detected or observed agent work.

Use the live app being served, rather than accidentally reading the dev queue when a dev instance is also recorded.

3. Make lifecycle status actionable

• list: show an explicit missing/stale local-bridge state for queueing apps, rather than an empty suffix. Include waiting-work information when available and distinguish unreadable/unknown from zero. Use wording such as "waiting work; no local bridge" rather than asserting that no external listener exists.
• bridge: reuse the shared inspection and make the combination of waiting work and no local bridge actionable, retaining harness-route diagnostics.
• stop: if a local bridge remains alive, state that it continues polling and give agent-app <dir> bridge stop. Do not stop it implicitly.

Bound queue probes so one unreachable app does not stall the whole list.

4. Finish creator and modify with a live delivery check

After promote and serve, for features that queue agent work:

• Inspect the live app's bridge/delivery state.
• Where app-triggered agent runs are authorized and a delivery route exists, start/reuse plain bridge start and confirm the background bridge remains running after the start command exits.
• --once, --dry-run, or an interactive foreground test do not satisfy the final handoff.
• If a harness subscribes independently, verify that delivery path where possible; do not invent a local bridge for a subscribe-only route.
• If delivery is unavailable or cannot be verified, explicitly report that limitation and the remedy. Do not describe the agent feature as operational solely because the server is healthy.

Keep #21's UI-state verification and #27's requeue protection; this check supplements them.

5. Verify the original failure and lifecycle cases

Add focused CLI regressions and an end-to-end handoff check:

• A one-shot test followed by serve leaves no persistent bridge: serve and list expose the gap.
• Fresh serve and already-serving paths produce consistent readiness output.
• A detached bridge is reused without duplication, survives the launching command/session ending, and delivers work queued afterward.
• Stale records are not reported as running; failed queue reads remain unknown.
• App stop/serve leaves an existing bridge running and it resumes delivery; stop explains that behavior.
• Apps without agent work stay quiet, including fixtures for capability-free events.
• Queueing apps without a View, live/dev separation, and subscribe-only routes are covered.
• Exercise a real Pi handoff for the original scenario, including a task queued after the build/test session has ended.

Acceptance criteria

• Serving a queueing app without a live local bridge prints a prominent delivery warning and exact remedy on both successful serve paths.
• App health and delivery readiness are separate in human and structured output.
• list and bridge expose waiting work plus missing/stale local-bridge state; unknown queue state is not reported as zero.
• Reports do not equate "no local bridge" with "no external listener," or "harness route available" with "delivery running."
• Creator/modify require a final live delivery check and leave a verified detached bridge for authorized bridge-based handoffs, or explicitly report the unresolved limitation.
• stop explains a bridge that continues running and how to stop it.
• The original Pi scenario is verified with new work queued after the initiating session ends.
• Enforce agent-state UX for app→agent features #21/fix: pocketbase kit #25's task UI and fix: prevent starters from requeuing unfinished agent work #27's unfinished-task guard remain intact.

Out of scope

Reimplementing the task-state UI or queue guards; silently enabling agent runs from serve; OS boot services; crash supervision; and a new protocol for discovering external subscribers.