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

159 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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:
```resources
{"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.