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.
This commit is contained in:
2026-10-18 12:30:30 +01:00
parent 88595ebd55
commit 9130ae8c7a
39 changed files with 2657 additions and 79 deletions
+26 -4
View File
@@ -20,16 +20,37 @@ time while iterating — the full suite is for the end.
## The dev device
Only the **UI reviewer**, while its stage holds a declared runner-exclusive resource
for the selected phone, may use the device. Implementers and code reviewers do code,
builds, unit tests and source review only: **no adb, installs, captures, device-setting
changes or main-build restoration**. Never acquire a phone using sleep/check loops.
Do not use the phone until compatible resource scheduling is deployed and every device
user has opted in or has been reconciled by the operator. Existing pinned runs are not
retroactively protected. The resource for the device below is `phone-47241FDAS00DLK`.
The only device is the operator's **Pixel 9 Pro XL, serial `47241FDAS00DLK`**. The operator's
Pixel 10 Pro Fold (`58281FDCG000JF`) is theirs: use it only where an item's brief explicitly allows
it, and never make it a default. **Never start or use an emulator.**
Before any capture: `svc power stayon usb`, `settings put global stay_on_while_plugged_in 7`,
The UI reviewer records original app connection/workspace, display size and power/settings
before changing them. Before any capture: `svc power stayon usb`, `settings put global stay_on_while_plugged_in 7`,
`input keyevent KEYCODE_WAKEUP`, `wm dismiss-keyguard`. Capture with
`adb -s <serial> shell screencap -p /sdcard/shot.png` then `adb pull` — never `exec-out > file`.
Wide layout: `wm size 2000x2244`; the fold's unfolded shape is `wm size 2076x2152`; `wm size reset`
afterwards either way.
Create controlled fixtures for changed screens/states (including human-decision sheets)
on a scratch server/database and throwaway session; never depend on incidental production
state, change a real operator session, or restart a deployed service. Use the configured
authoritative endpoint, never a scratch URL as a project default. Keep all shell/ADB work
foreground and awaited: no detached/background processes may outlive the lease.
UI review includes restoring the captured original settings and main's build before its
successful return. Confirm every tool has exited. If capture, restoration or cleanup fails,
report the failure explicitly; do not claim verification or readiness. Uncertain termination
must fail closed and keep ownership quarantined, not delete a lock or expire it by age.
Return `output.resource_cleanup_confirmed=false` if restoration/readiness is uncertain;
that generic release veto retains the runner lease even if the harness reports idle.
## Geometry is tokenised, and a test enforces it
Every dimension comes from `ui/theme/Dimens.kt` (plus the layout itself) — no new hardcoded `dp`, no
@@ -53,13 +74,14 @@ genuinely needs a new token goes there, named for its purpose.
## Publishing a build
Copy the APK into the running run's artifacts directory as `pipelines-debug-wip-<short-HEAD>.apk` and
report the LAN URL. After any install, leave the operator's phone on **main's** build:
report the LAN URL. The UI reviewer alone, under the same lease, restores **main's** build after an install:
`/private/var/folders/jp/q0qvjyg54fl_c5vhhk1ylz2m0000gn/T/opencode/deploy-app.sh main`.
## Traps
- A build made in a worktree that is behind main is missing features main has — sync before building,
and say which revision you built.
- Changing the app's server URL for a test (a stub) must be undone: `ws://10.0.0.75:8080/connect`,
workspace `/Users/alan/repos/pipelines`, then force-stop and relaunch.
- Restore the app's captured original connection and workspace after a fixture test,
using the configured authoritative endpoint; then force-stop and relaunch under the lease.
Never substitute a hardcoded or disposable scratch endpoint for the original configuration.
- `mStayOn`/screen timeout are already set; do not "fix" the device by locking or sleeping it.
@@ -315,6 +315,7 @@ data class SessionExport(
@Serializable
data class RunSummary(
@SerialName("resource_wait") val resourceWait: ResourceWait? = null,
val id: Long = 0,
@SerialName("pipeline_id") val pipelineId: Long = 0,
val name: String = "",
@@ -370,6 +371,7 @@ data class RunStep(
// declared directly with the exact internal/protocol/runs.go wire names.
@Serializable
data class RunDetail(
@SerialName("resource_wait") val resourceWait: ResourceWait? = null,
val id: Long = 0,
@SerialName("pipeline_id") val pipelineId: Long = 0,
val name: String = "",
@@ -405,6 +407,8 @@ data class RunDetail(
*/
@Serializable
data class RunEventFrame(
@SerialName("resource_wait") val resourceWait: ResourceWait? = null,
@SerialName("resource_wait_set") val resourceWaitSet: Boolean = false,
@SerialName("run_id") val runId: Long = 0,
val workspace: String = "",
// The run's pipeline identity and stored title, repeated on every frame so a
@@ -428,6 +432,16 @@ data class RunEventFrame(
val step: RunStepDelta? = null,
)
@Serializable
data class ResourceWait(
val resource: String = "",
val stage: String = "",
val sequence: Int = 0,
@SerialName("queued_since") val queuedSince: String = "",
) {
fun statusLabel(): String = "Waiting for resource $resource"
}
/**
* The compact change of one step within a [RunEventFrame]
* (internal/protocol/runevents.go RunStepDelta): a delta, not a RunStep, so it
@@ -101,6 +101,7 @@ internal fun foldRunEvent(runs: List<RunSummary>, frame: RunEventFrame): RunList
internal fun RunEventFrame.newRunSummary(): RunSummary? {
if (pipelineId <= 0 || name.isBlank()) return null
return RunSummary(
resourceWait = resourceWait,
id = runId,
pipelineId = pipelineId,
name = name,
@@ -124,10 +125,11 @@ internal fun RunEventFrame.newRunSummary(): RunSummary? {
*/
internal fun foldRunEvent(detail: RunDetail, frame: RunEventFrame): RunDetail {
if (frame.runId != detail.id) return detail
if (isStaleRunFrame(detail.status, frame.status)) return detail
if (isStaleRunFrame(detail.status, frame.status, frame.resourceWaitSet)) return detail
val merged = detail.fields().applying(frame)
val steps = frame.step?.let { upsertStep(detail.steps, it) } ?: detail.steps
val updated = detail.copy(
resourceWait = merged.resourceWait,
status = merged.status,
outcome = merged.outcome,
currentStage = merged.currentStage,
@@ -169,8 +171,9 @@ private fun advanceRunStatus(current: String, incoming: String): String =
* run already settled. Dropping every field (not just the status) is what keeps
* a late `running` delta from also rewriting the stage or step of a settled run.
*/
private fun isStaleRunFrame(current: String, incoming: String): Boolean =
isStaleTransition(current, incoming, ::runLifecycleRank)
private fun isStaleRunFrame(current: String, incoming: String, resourceWaitSet: Boolean = false): Boolean =
if (resourceWaitSet && incoming == "queued" && !isTerminalRunStatus(current)) false
else isStaleTransition(current, incoming, ::runLifecycleRank)
/** The step counterpart of [isStaleRunFrame]: a settled visit drops a stale delta whole. */
private fun isStaleStepDelta(current: String, incoming: String): Boolean =
@@ -213,6 +216,7 @@ private fun advanceStatus(current: String, incoming: String, rank: (String) -> I
/** The run-state fields a frame advances, shared by the summary row and the detail. */
private data class RunStateFields(
val resourceWait: net.awan.pipelines.data.protocol.ResourceWait?,
val status: String,
val outcome: String,
val currentStage: String,
@@ -226,8 +230,10 @@ private data class RunStateFields(
* detail can never apply a frame differently.
*/
fun applying(frame: RunEventFrame): RunStateFields {
val status = advanceRunStatus(status, frame.status)
val status = if (frame.resourceWaitSet && frame.status == "queued" && !isTerminalRunStatus(status))
"queued" else advanceRunStatus(status, frame.status)
return RunStateFields(
resourceWait = if (isTerminalRunStatus(status)) null else if (frame.resourceWaitSet) frame.resourceWait else resourceWait,
status = status,
outcome = frame.outcome.ifBlank { outcome },
currentStage = frame.currentStage.ifBlank { currentStage },
@@ -240,6 +246,7 @@ private data class RunStateFields(
}
private fun RunSummary.fields() = RunStateFields(
resourceWait = resourceWait,
status = status,
outcome = outcome,
currentStage = currentStage,
@@ -250,6 +257,7 @@ private fun RunSummary.fields() = RunStateFields(
)
private fun RunDetail.fields() = RunStateFields(
resourceWait = resourceWait,
status = status,
outcome = outcome,
currentStage = currentStage,
@@ -267,11 +275,12 @@ private fun executingFor(status: String, current: Boolean): Boolean = when (stat
}
private fun RunSummary.applying(frame: RunEventFrame): RunSummary {
if (isStaleRunFrame(status, frame.status)) return this
if (isStaleRunFrame(status, frame.status, frame.resourceWaitSet)) return this
val current = fields()
val merged = current.applying(frame)
if (merged == current) return this
return copy(
resourceWait = merged.resourceWait,
status = merged.status,
outcome = merged.outcome,
currentStage = merged.currentStage,
@@ -615,6 +615,7 @@ private fun VersionChip(version: String) {
/** Progress from the fields a summary actually has: completed visits + stage. */
private fun progressText(run: RunSummary): String = buildString {
run.resourceWait?.let { append(it.statusLabel()); append(" · ") }
append(visitCount(run.completedSteps, "completed"))
if (run.currentStage.isNotBlank()) append(" · stage ${run.currentStage}")
}
@@ -133,6 +133,7 @@ internal fun RunSummaryTab(
)
KeyValueRow("Pipeline", "id ${run.pipelineId} · v${run.version}")
KeyValueRow("Stage", run.currentStage)
run.resourceWait?.let { Text(it.statusLabel(), style = text.meta) }
KeyValueRow("Workspace", run.workspace)
KeyValueRow("Content hash", run.contentHash, monospace = true)
KeyValueRow("Started", formatLocalTimestamp(run.createdAt).orEmpty())
@@ -0,0 +1,32 @@
package net.awan.pipelines.ui
import kotlinx.serialization.json.Json
import net.awan.pipelines.data.protocol.ResourceWait
import net.awan.pipelines.data.protocol.RunDetail
import net.awan.pipelines.data.protocol.RunEventFrame
import net.awan.pipelines.data.protocol.RunSummary
import org.junit.Assert.*
import org.junit.Test
class ResourceWaitTest {
@Test fun optionalMetadataAndPauseResumeClearing() {
val json = Json { ignoreUnknownKeys = true }
assertNull(json.decodeFromString<RunDetail>("""{"id":1,"status":"queued"}""").resourceWait)
val wait = ResourceWait("phone-X", "review", 2, "2026-10-18T10:00:00Z")
val queued = RunEventFrame(runId = 1, status = "queued", resourceWaitSet = true, resourceWait = wait)
val detail = foldRunEvent(RunDetail(id = 1, status = "running"), queued)
assertEquals("queued", detail.status)
assertEquals(wait, detail.resourceWait)
assertEquals("Waiting for resource phone-X", wait.statusLabel())
val rows = foldRunEvent(listOf(RunSummary(id = 1, status = "running")), queued).runs
assertEquals(wait, rows.single().resourceWait)
val clear = RunEventFrame(runId = 1, status = "running", resourceWaitSet = true)
assertNull(foldRunEvent(detail, clear).resourceWait)
assertNull(foldRunEvent(rows, clear).runs.single().resourceWait)
assertNull(foldRunEvent(detail, RunEventFrame(runId = 1, status = "canceled")).resourceWait)
assertEquals("succeeded", foldRunEvent(RunDetail(id = 1, status = "succeeded"), queued).status)
val decoded = json.decodeFromString<RunDetail>("""{"id":1,"status":"queued","resource_wait":{"resource":"phone-X","stage":"review","sequence":2,"queued_since":"now"}}""")
assertEquals("phone-X", decoded.resourceWait?.resource)
assertFalse(isWaitingRunStatus(decoded.status))
}
}