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:
+26
-4
@@ -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))
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user