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
@@ -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))
}
}