Files
pipelines/docs/notes/phone-resource-wait.md
T
alan 9130ae8c7a Add stage-exclusive resource waiting
Add durable FIFO capacity-one resource leases for executable stages, including cleanup-confirmed release, conservative restart quarantine, queue state events, and CLI/TUI/Android waiting presentation. Add scheduler, cleanup, protocol, client, and Android coverage plus a proposed Android v3 resource draft.

Checked packaged templates and authoring skill references: neither needs updating in this item. The per-item docs note records the shared documentation that docs-fold must update; no shared README or packaged reference was edited.
2026-10-18 12:30:30 +01:00

11 KiB
Raw Blame History

Stage-exclusive resources — 2026-10-18, not deployed

This is source work for run 355, not a deployment, installation or publication. No physical phone, real operator session or deployed service was used or changed. The Android role split does not retrospectively gate pinned versions or existing runs.

Contract and scope

An executable non-human stage can declare one runner-owned control block:

{"exclusive":"phone-47241FDAS00DLK"}

The key is 1–128 ASCII identifier bytes (letter first, then letters, digits, _, -). Duplicate/unknown fields, multiple resources and human-stage resources are rejected. One capacity-one resource per stage visit, one server/store authority; no expressions, nested acquisition, distributed scheduling, capacity settings or multi-resource requests. Resource-free definitions retain their execution path. Old servers reject this new block; do not publish to an incompatible server.

Acquisition follows selection and automatic UI-skip evaluation, before BeginStep, visits/sequences, artifacts, filediff, stage timeout, budget setup or executor calls. Queued runs retain workspace reservation, use legacy queued (never human waiting), and carry bounded resource_wait identity/stage/sequence/queued-since metadata. Events use resource_wait_set=true with absent resource_wait to clear caches. CLI lists and TUI/Android details show “Waiting for resource …”; human decisions and attention notifications remain separate. Older clients still see an unfinished run.

SQLite owners and FIFO waiters are indexed by resource/order and run identity. Private random capabilities attribute ownership to resource/run/stage/sequence and never enter wire data, model input, transcripts or artifacts. Only the full capability and positive cleanup evidence authorize release; mismatches and repeated release cannot release a subsequent owner. One buffered channel per live queued run, no resource polling, waiter tickers, model-based acquisition, queue driver or new daemon.

The gate holds through tool cleanup. OpenCode interruption now confirms session idle/ V1 settlement before clearing session ownership. Pi recovery requires both its receipt and process/process-group exit, not merely abort acknowledgement. Executor panic, ErrStageCleanup, retained active sessions and failed cleanup queries quarantine the owner. An explicit output.resource_cleanup_confirmed=false (or malformed value) also vetoes release for failed restoration; true never substitutes for harness cleanup evidence. The generic runner does not inspect Android settings or magically verify restoration. The Android UI reviewer must keep all device work foreground/awaited, restore original settings/connection and main's build, and report uncertainty with the release veto.

Restart and retention

Automatic FIFO progress is promised only within a live server process. Startup interrupts persisted queued resource visits, removes their waiter rows, and never replays an executor. Durably cleanup-confirmed owners can be reclaimed through the token-checked delete helper. Unconfirmed owners remain quarantined, including crashes before BeginStep, before session registration, or after cleanup but before its confirmation is persisted. Session interruption alone cannot prove resource-specific restoration. Age never authorizes reclamation. Quarantined ownership/session evidence survives recovery and protects even terminal runs from retention. Reconciliation requires inspected cleanup and restoration, not lock deletion. There is intentionally no force-unlock CLI or automatic uncertain-owner reclamation.

Android draft, provenance and activation

Read-only retrieval: pipelines show Android --version 2 --json returned pipeline 20, v2, hash 8c93aeb9b76f1e6e7696415d6308d786ec08d805a1a346fbabe4d252d5d65032. python3 recomputed SHA-256 of the returned source and asserted equality. The exact source is retained as internal/server/testdata/android-v2-published.md; the proposed source is internal/server/testdata/android-resource-draft.md. The provenance test compares graph fields/outcomes unchanged, apart from the approved three stage prompts and the UI review resource; every stage keeps its published v3 model: Terra for implementer/committer and Luna for reviewer/UI reviewer. No unrelated published definition was edited.

Artifact handoff recovery: the validated v3 draft was copied to this run's retained artifact directory as android-resource-draft.md. The similarly named artifact from run 355 remains the old v2 baseline and must not be published. The proposed source in this workspace and this run's artifact have matching SHA-256 digests a10d8b9fa3dc6a1875b10469061ed25fb4a7a404d463d1a2d304a309d55aa5d9.

Activation, requiring separate explicit operator authorization:

  1. Review/land the source change and independently rerun the required checks.
  2. Arrange a compatible deployment separately; nothing here deploys or restarts it.
  3. Reconcile every existing phone user, pinned/live run and any quarantined owner.
  4. Transfer the workspace proposed draft, provenance and this note into the retained stage artifacts after resolving the artifact edit permission.
  5. Validate that retained draft against the configured authoritative compatible endpoint; only then explicitly publish it. Do not use a disposable endpoint as a project default.
  6. Opt in other device users explicitly before relying on mutual exclusion system-wide.

Read-only published inventory (pipelines show <name> --json, v2 for each):

  • UI sweep: survey and ui_reviewer request visual/screenshots work; phone work there needs explicit resource opt-in and restoration/fixture policy.
  • Generic: reviewer and ui_reviewer have visual/device verification wording; when targeting a phone, separate code review from leased device review first.
  • Plan and land: implementer, reviewer, ui_reviewer contain rendered-surface work; they need an explicit technology-specific role split/lease before phone use.
  • Probe: one harness smoke stage; no default phone declaration. Any device-specific probe needs explicit opt-in, never an inferred resource or Android stage-name special case. Server/TUI/other definitions were not changed. Inventory is not activation evidence.

Verification evidence and remaining limits

Executed focused checks:

  • Run 358 recovery revalidation: go build ./... && go vet ./... && go test ./... passed; go test -race ./internal/pipeline ./internal/server ./internal/stage -run 'Resource|Scheduler|Concurrent|Human|Decision|RetryWaits' -count=1 passed; and the Android map invocation with JAVA_HOME/ANDROID_HOME, installed Gradle, --offline --no-daemon --rerun-tasks :app:assembleDebug :app:testDebugUnitTest executed all 41 tasks and reported BUILD SUCCESSFUL. These remain build/unit and fake-executor scheduler evidence, not physical-phone verification or screenshots.
  • Recovery after integrating main 88595eb: go build ./..., go vet ./..., go test ./internal/server -run Resource -count=1, go test ./internal/pipeline ./internal/protocol ./internal/tui -run Resource -count=1, go test ./internal/stage -count=1, go test -race ./internal/pipeline ./internal/server ./internal/stage -run 'Resource|Scheduler|Concurrent|Human|Decision|RetryWaits' -count=1, and go test ./... all passed. gofmt -l . and git diff --check produced no output.
  • Recovery Android build/unit check with the map's offline, no-daemon Gradle invocation: :app:assembleDebug :app:testDebugUnitTest passed. This remains build/unit evidence, not phone verification or screenshots.
  • go test ./internal/server ./internal/pipeline ./internal/protocol ./internal/tui -run Resource -count=1: passed. Includes fake-executor queue >30ms timeout, independent-resource progress, FIFO/mismatch/duplicate/grant-cancel cycles, blocked cleanup, panic/quarantine, persistence/BeginStep/query failure, no-acquire skip, restart/retention, wire defaults, narrow/wide/plain TUI frames and real CLI/WebSocket scratch exercise.
  • go test ./internal/stage -count=1: passed; the later full suite also included TestResourcePiReceiptRequiresProcessExit (a test-owned sleep process, not a device).
  • Android map invocation with JAVA_HOME/ANDROID_HOME and installed Gradle, --offline --no-daemon :app:assembleDebug :app:testDebugUnitTest: BUILD SUCCESSFUL. These are build/unit checks, not device verification or screenshots.
  • After the Go tree settled: go build ./..., go vet ./..., go test ./... all exited zero (including author-package tests).
  • go test -race ./internal/pipeline ./internal/server ./internal/stage -run 'Resource|Scheduler|Concurrent|Human|Decision|RetryWaits' -count=1: all three packages passed, including concurrent grant/cancel cycles.
  • gofmt -l . and git diff --check: exited zero with no output.

The scratch CLI test uses the real CLI and WebSocket handler with temporary SQLite and an explicitly FAKE executor. It validates the proposed Android draft on compatible scratch code, observes B as queued with zero steps while A holds fake-phone, inspects subscription metadata, releases A, runs wait, and observes B succeeded automatically. It does not call a model or use a physical phone. Test log output is evidence, not a live-deployment claim; no retained CLI transcript was written to the denied artifact path.

Live OpenCode/Pi shell/ADB termination and Android visual/device restoration are not tested here. The checks prove scheduler behavior with controlled fakes, plus test-owned process-exit checks, not device readiness on the current deployment. Commit/merge/landing belong to the later committer stage; no commit or push here.

Stale shared documentation for docs-fold (do not edit in this item)

  • docs/cli.md: resource queue presentation, inspection metadata, unchanged wait/decide semantics.
  • internal/author/skill/references/format.md: optional resources block and validation/key bounds.
  • internal/author/skill/references/control.md: runner-owned declaration, timeout/accounting boundary, release veto and automatic skip placement.
  • internal/author/skill/references/queue.md: FIFO resource waits vs workspace exclusion and human waits.
  • internal/author/skill/references/operations.md: authority, restart interruption/quarantine, inspected recovery, retention and explicit compatible-deployment/publication prerequisites.
  • internal/author/skill/references/verification.md: fake-vs-device evidence, fixtures and leased restoration.
  • internal/author/skill/references/orchestration.md: no queue drivers/polling/extra agents; explicit opt-in of every device user, no retroactive gating or distributed guarantees.

No packaged skill/reference, shared README/topic documentation, pipeline registry, installation, deployment, provider setting or internal/stage/model_failure.go was edited.