9130ae8c7a
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.
159 lines
11 KiB
Markdown
159 lines
11 KiB
Markdown
# 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.
|