@kungfu-tech/buildchain 3.0.6-alpha.0 → 3.0.6-alpha.10

package/docs/auditable-demo.md

@@ -8,7 +8,7 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: self-reviewed
-last_reviewed: 2026-08-02
+last_reviewed: 2026-08-05
 ai_provenance:
   model_family: GPT-5
   product: Codex
@@ -52,6 +52,39 @@ the default. Both classes retain 4 MiB per step, a clean Home/XDG environment,
 no inherited credentials, and a network-disabled read-only container with
 bounded tmpfs.
 
+Consumers may optionally add a
+`buildchain.declarative-demo-presentation/v1` presentation. This contract
+binds one consumer-owned proof label, question, summary, and optional
+transition to every demo in declared order. Buildchain verifies that each
+question is the same title used by capture and media; it does not invent or
+reinterpret the product argument.
+
+The presentation also chooses one of two README materialization modes. The
+default, when no presentation is declared, remains the original full generated
+block with commands, renditions, evidence, and claim boundary. `media-only`
+updates only the image inside each existing README marker so consumer-authored
+narrative and transitions survive regeneration. The generated technical
+details move to a separately declared Markdown specification, where stable
+per-demo markers preserve proof order and idempotent updates. The publication
+pull request stages that specification together with the README and
+content-addressed evidence. No presentation field grants publication or Work
+authority.
+
+The optional top-level `compositionMode` is an explicit visual contract.
+Omitting it preserves `presentation-framed`; declaring `terminal-fill` makes
+the bounded PTY replay the complete pixel surface without renderer-owned
+window chrome. Buildchain carries that choice into both native scenes. It does
+not infer full-frame intent from output resolution.
+
+The optional `buildchain.declarative-demo-playback/v1` contract separates
+observed command latency from presentation timing. Its
+`deterministic-readable` mode preserves the captured terminal event payloads
+and their order, records the observed final-event time as non-authoritative
+evidence, and maps event ordinals onto the declared `activeDurationMs` before a
+bounded `finalHoldMs`. Both native renditions therefore replay at the same
+readable pace even when an identical command runs faster or slower. Omitting
+the contract preserves the original PTY timestamp behavior.
+
 The uploaded metadata must bind the executable SHA-256, declare an empty
 runtime dependency set, and provide a bounded `executableFiles` array of exact
 artifact-relative paths and SHA-256 digests. GitHub Artifact transport does not
@@ -97,6 +130,7 @@ jobs:
       scenario-path: .buildchain/auditable-demo.json
       renderer-image: ghcr.io/kungfu-systems/build-images/demo-renderer@sha256:RENDERER_DIGEST
       render-media: true
+      render-failure-advisory: false
       media-profile: responsive-web-delivery-v1
       materialize: true
       materialize-base-ref: dev/v1/v1.0
@@ -193,6 +227,10 @@ The Gate:
   bounded tmpfs;
 - verifies the renderer manifest, media probe, exact input roots, exact output
   member set, and complete checksums;
+- independently verifies the requested composition mode, browser-observed
+  content viewport, PTY rows and columns, and deterministic cell geometry for
+  every frame set; `terminal-fill` is rejected unless the viewport and cell
+  grid resolve to the complete declared frame;
 - uploads a content-addressed qualified bundle plus an independent GitHub
   Artifact id, URL, archive digest, and expiry-bearing source coordinate.
 
@@ -202,9 +240,9 @@ passed gate receipt, and checksums covering every member exactly once.
 
 ## Selective Render
 
-`render-media: true` enables the second job. It downloads the just-uploaded Gate
-bundle by its content-addressed name, recomputes the Gate member root, verifies
-the exact source SHA and renderer digest, and only then renders the complete
+`render-media: true` enables the full-media step only after every declared demo
+has passed the required Gate. It recomputes each Gate member root, verifies the
+exact source SHA and renderer digest, and only then renders the complete
 qualified scene.
 
 The media bundle contains MP4, WebM, GIF, poster, probe, renderer manifest,
@@ -213,10 +251,19 @@ distribution checksums. A web-delivery profile also retains
 `media-inspection.json`, whose content root is bound into the receipt.
 `render-media: false` does not weaken or skip the Gate.
 
+`render-failure-advisory: true` makes only the full-media step advisory. A
+render failure remains visible as a failed step and workflow warning, while the
+required Gate keeps its normal failure semantics. Failed or partial media can
+never open a materialization PR. Use this for an Alpha lane whose binary
+publication must not depend on animation capacity; keep the default `false`
+for explicit media refreshes and other workflows that require complete media.
+
 When the Gate bundle contains a qualified terminal capture, the render job
 passes it read-only to the immutable renderer. The renderer manifest binds the
 capture root and terminal-state-machine version, but raw capture bytes remain
 in the Gate bundle rather than being copied into the public media bundle.
+Missing, malformed, out-of-bounds, non-full-frame, rendition-mismatched, or
+internally drifted composition evidence fails before media finalization.
 
 ## Media Qualification Profiles
 
@@ -225,13 +272,13 @@ The single machine-readable source is
 profile through `media-profile`; they cannot pass ffmpeg commands, codec flags,
 shell fragments, arbitrary profile paths, or transcoding instructions.
 
-| Profile | Meaning |
-| --- | --- |
-| `archive-v1` | Default compatibility contract. Retains the exact renderer outputs and classifies GIF as README compatibility evidence without making a browser-delivery claim. |
-| `web-delivery-v1` | Independently qualifies H.264 MP4 and VP9 WebM playback sources, forbids audio, requires exact scene dimensions and bounded duration/frame-rate drift, checks per-rendition byte ceilings, and proves MP4 `moov` precedes `mdat`. PNG remains the lossless evidence poster. |
-| `responsive-web-delivery-v1` | Extends `web-delivery-v1` with exact 1280x720 H.264 MP4 and VP9 WebM responsive sources plus a 1280x720 README GIF while keeping the primary MP4/WebM and evidence poster at the source scene dimensions. Every declared downscale must preserve the scene aspect ratio and may never upscale. |
-| `responsive-long-form-web-delivery-v1` | Extends the responsive profile for explicitly admitted long-form scenes. Its measured-baseline multipliers raise only the GIF ceiling to 8 MiB and the four video ceilings to 4 MiB; all codec, native-resolution, no-audio, duration, and authority checks remain unchanged. |
-| `site-hero-v1` | Extends `web-delivery-v1` and additionally requires a qualified WebP browser poster. The current Build Images v1 renderer does not emit that member, so selecting this profile fails closed until the producer adds it. |
+| Profile                                | Meaning                                                                                                                                                                                                                                                                                        |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `archive-v1`                           | Default compatibility contract. Retains the exact renderer outputs and classifies GIF as README compatibility evidence without making a browser-delivery claim.                                                                                                                                |
+| `web-delivery-v1`                      | Independently qualifies H.264 MP4 and VP9 WebM playback sources, forbids audio, requires exact scene dimensions and bounded duration/frame-rate drift, checks per-rendition byte ceilings, and proves MP4 `moov` precedes `mdat`. PNG remains the lossless evidence poster.                    |
+| `responsive-web-delivery-v1`           | Extends `web-delivery-v1` with exact 1280x720 H.264 MP4 and VP9 WebM responsive sources plus a 1280x720 README GIF while keeping the primary MP4/WebM and evidence poster at the source scene dimensions. Every declared downscale must preserve the scene aspect ratio and may never upscale. |
+| `responsive-long-form-web-delivery-v1` | Extends the responsive profile for explicitly admitted long-form scenes. Its measured-baseline multipliers raise only the GIF ceiling to 8 MiB and the four video ceilings to 4 MiB; all codec, native-resolution, no-audio, duration, and authority checks remain unchanged.                  |
+| `site-hero-v1`                         | Extends `web-delivery-v1` and additionally requires a qualified WebP browser poster. The current Build Images v1 renderer does not emit that member, so selecting this profile fails closed until the producer adds it.                                                                        |
 
 For web-delivery profiles, Buildchain runs its own fixed `ffprobe` invocation
 inside the same immutable, network-disabled renderer image. That command is

package/docs/aws-us-elastic-runner-burst-plane.md

@@ -8,11 +8,11 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-08-02
+last_reviewed: 2026-08-03
 ai_provenance:
   model_family: GPT-5
   product: Codex
-  generated_at: 2026-08-01
+  generated_at: 2026-08-03
   invisible_information: No hidden model checkpoint, parameters, or private training data were available.
 ---
 
@@ -189,7 +189,7 @@ and atomically refuses a sixth accepted instance. Five accepted instances
 therefore reserve at most USD 21.75. The campaign also persists the
 operator-observed spend from earlier Windows work, and refuses to arm unless
 that baseline, all five reservations, and one USD 4.35 fail-closed race
-allowance remain below the USD 80 phase cap.
+allowance remain below the USD 110 phase cap.
 
 The campaign starts unarmed and expires within 24 hours. Its `CONTROL` record
 can be created only once: a killed or expired campaign cannot be re-armed by
@@ -199,16 +199,38 @@ paid launch. Reservations are never refunded: a controller crash, ambiguous
 launch, or successful launch all remain charged to the campaign, favoring a
 false stop over an accidental budget overrun.
 
+The 2026-08-03 timeout-only campaign decision narrows the campaign to two
+accepted instances with one active instance at a time. The second reservation
+is an operator-gated repair retry: it may be used only after the first attempt
+is classified as non-counting and runner, EC2, EBS, SSM, and workflow residue
+have returned to zero. The two-slot ledger is a maximum spend boundary, not an
+authorization to consume both reservations.
+
 Each stack owns a stack-scoped reaper log group, so an independent retained
 one-shot campaign stack can be created without colliding with another
 campaign's audit log resource.
 
-The tag-filtered AWS Budget is defense in depth, not the authoritative launch
-gate. It is disabled by default because a linked account cannot activate a
-cost-allocation tag. Set `EnableTagFilteredBudget=true` only after the AWS
-Organizations management account has activated `kungfu:provider` and a Cost
-Explorer readback proves that `windows-ec2-jit` spend is visible. The DynamoDB
-reservation cap remains mandatory in either mode.
+The account-native AWS Budget is defense in depth, not the authoritative launch
+gate. It is owned by the singleton
+`kungfu-buildchain-windows-jit-budget-guard` stack rather than any retained
+campaign stack. This prevents Budget-name collisions and prevents a stale
+campaign reaper from becoming the provider-wide cost authority. The Budget
+filters exactly `USAGE_TYPE=BoxUsage:c7i.4xlarge`,
+`OPERATION=RunInstances:0002` (Windows), and `REGION=us-east-1`; its 80% and
+95% actual notifications persist the provider kill sentinel, terminate every
+tagged Windows JIT instance, and delete scoped JIT parameters. Every launch
+controller refuses to proceed when the sentinel exists or when the Budget
+identity or dimension filter does not match.
+
+Budget installation is intentionally deployable by the workload account without
+AWS Organizations management-account access. It fails closed unless Cost
+Explorer exposes all three AWS-owned billing dimensions in the requested phase
+window. The `kungfu:provider=windows-ec2-jit` resource tag remains mandatory for
+ownership, cleanup, and IAM scoping, but it is not a billing filter. Do not
+create an unfiltered fallback Budget or treat an incomplete dimension readback
+as evidence.
+The DynamoDB campaign reservation remains the atomic launch authority because
+Cost Explorer and AWS Budgets can lag provider activity.
 
 Qualification requires one runner-profile smoke and three trusted exact-source
 full Windows jobs all bound to the same campaign, independent cancellation and
@@ -216,82 +238,94 @@ timeout cleanup exercises, and zero repository runner, EC2 instance,
 disposable volume, min capacity, and desired capacity within 15 minutes of the
 final job.
 
-### Phase 2 campaign controller
-
-`scripts/aws-windows-jit-campaign.mjs` is the one-shot operator boundary.
-Without a mutation mode it emits the arm plan. `arm-campaign` requires the
-campaign id, exact source SHA, state table, observed prior phase spend, and a
-bounded one-to-five accepted-instance ceiling to be repeated as confirmations,
-then creates `CONTROL` and `CAMPAIGN#<id>` with
-`attribute_not_exists`
-conditions. DynamoDB therefore refuses a second campaign in the same retained
-state table. The operator can always use `kill-campaign`; there is deliberately
-no clear or re-arm operation.
-
-Every `scripts/aws-windows-jit-controller.mjs --execute` call must provide the
-same `--campaign-id`, `--confirm-campaign-id`, `--state-table`, and
-`--confirm-state-table`. After the GitHub, AMI, active-instance, SSM, and EC2
-DryRun checks pass, the controller
-atomically reserves one run. Duplicate run-attempt-qualification identities,
-source mismatch, expiry, `KILLED`, the sixth accepted instance, or a
-reservation that would exceed the baseline-adjusted USD 80 phase ceiling all
-fail closed before `RunInstances`.
-
-Example dry-run and arm boundary (do not execute without a new campaign budget
-decision):
+### Phase 2 operator workflow
+
+`pnpm operator:windows-jit` is the reusable lifecycle entrypoint. Its default
+mode is `plan`, which performs no AWS or GitHub call. A plan binds the account,
+region, unique campaign and stack names, source SHA/ref, Cost Explorer window,
+workflow id, network, OIDC provider, expiry, slot ceiling, singleton Budget
+identity, and exact confirmation digest.
+
+The modes are deliberately separated:
+
+- `plan` emits the deterministic mutation boundary and digest.
+- `audit` reads AWS and GitHub only. It verifies the account, disabled workflow,
+  singleton guard stack, exact Budget filter, SNS thresholds/subscribers,
+  provider kill sentinel, campaign stack, and zero EC2/EBS/SSM/JIT/runner
+  residue.
+- `install-budget --execute` deploys or updates only the singleton Budget guard.
+  It refuses to mutate unless all exact Windows billing dimensions are visible,
+  the Windows workflow is disabled, and the account, campaign, source, Budget,
+  and plan digest confirmations match.
+- `prepare --execute` requires the installed Budget guard, absent kill
+  sentinel, fresh Cost Explorer readback filtered by `BoxUsage:c7i.4xlarge`,
+  `RunInstances:0002`, and `us-east-1`, zero residue, a
+  never-used campaign stack name, and the disabled workflow. The receipt binds
+  the query timestamp and exact filter identity. Preparation deploys the
+  campaign stack and atomically arms the ledger with that provider-spend
+  baseline. It never enables or dispatches the workflow and never creates EC2
+  capacity.
+- `close --execute` disables the workflow first, persists `KILLED`, publishes
+  the campaign kill switch, and reports terminal success only after EC2, EBS,
+  SSM, JIT parameter, and GitHub runner residue is zero. It is safe to rerun
+  while the reaper settles.
+
+All mutating modes require `--execute`, `--confirm-plan-digest`,
+`--confirm-account-id`, `--confirm-campaign-id`, and
+`--confirm-source-sha`. Budget installation and preparation additionally
+require `--confirm-budget-name`. A future paid workload still requires a
+separate exact workflow/run authorization and uses
+`scripts/aws-windows-jit-controller.mjs`; preparation is not paid-launch
+authority.
+
+Start by recording one reproducible plan:
 
 ```bash
-windows_campaign=win-REPLACE_WITH_CAMPAIGN_ID
-windows_source=REPLACE_WITH_EXACT_40_CHARACTER_SHA
-windows_state_table=REPLACE_WITH_CAMPAIGN_STATE_TABLE
-windows_expires_at=REPLACE_WITH_ISO_TIMESTAMP_WITHIN_24_HOURS
-windows_phase_spend_baseline_usd=REPLACE_WITH_OBSERVED_PRIOR_WINDOWS_SPEND
-windows_max_accepted_instances=REPLACE_WITH_INTEGER_FROM_1_THROUGH_5
-
-node scripts/aws-windows-jit-campaign.mjs plan-arm \
-  --campaign-id "$windows_campaign" \
-  --source-sha "$windows_source" \
-  --state-table "$windows_state_table" \
-  --expires-at "$windows_expires_at" \
-  --phase-spend-baseline-usd "$windows_phase_spend_baseline_usd" \
-  --max-accepted-instances "$windows_max_accepted_instances"
-
-node scripts/aws-windows-jit-campaign.mjs arm-campaign \
-  --campaign-id "$windows_campaign" \
-  --confirm-campaign-id "$windows_campaign" \
-  --source-sha "$windows_source" \
-  --confirm-source-sha "$windows_source" \
-  --state-table "$windows_state_table" \
-  --confirm-state-table "$windows_state_table" \
-  --expires-at "$windows_expires_at" \
-  --phase-spend-baseline-usd "$windows_phase_spend_baseline_usd" \
-  --confirm-phase-spend-baseline-usd "$windows_phase_spend_baseline_usd" \
-  --max-accepted-instances "$windows_max_accepted_instances" \
-  --confirm-max-accepted-instances "$windows_max_accepted_instances"
+pnpm operator:windows-jit plan \
+  --aws-profile us \
+  --account-id 727884401362 \
+  --campaign-id win-REPLACE \
+  --source-sha REPLACE_WITH_EXACT_40_CHARACTER_SHA \
+  --source-ref refs/heads/dev/v4/v4.0 \
+  --observed-at REPLACE_WITH_ISO_TIMESTAMP \
+  --expires-at REPLACE_WITH_ISO_TIMESTAMP_WITHIN_24_HOURS \
+  --cost-start REPLACE_WITH_PHASE_START_DATE \
+  --cost-end REPLACE_WITH_EXCLUSIVE_END_DATE \
+  --max-accepted-instances 1 \
+  --workflow-id 322620360 \
+  --vpc-id REPLACE_WITH_VPC_ID \
+  --subnet-id REPLACE_WITH_SUBNET_ID \
+  --oidc-provider-arn REPLACE_WITH_GITHUB_OIDC_PROVIDER_ARN
 ```
 
-Arming creates a permanent one-shot control record and admits only the
-explicitly confirmed number of paid instances, never more than five. Its
-rollback is fail-closed, not deletion: `kill-campaign` first
-persists `KILLED`, then publishes to the dedicated SNS topic so the reaper
-terminates active card-owned instances and removes their JIT parameters. The
-command is idempotent, but the operator must read back DynamoDB, EC2, SSM, and
-GitHub runners before treating cleanup as complete:
+Reuse those exact arguments for `audit`, `install-budget`, `prepare`, or
+`close`; never regenerate `--observed-at` between the plan and its confirmed
+mutation. Capture stdout as the operator receipt. Do not put credentials,
+tokens, JIT configuration, or signed URLs in arguments or receipts.
 
-```bash
-windows_kill_topic=REPLACE_WITH_DEDICATED_KILL_SWITCH_TOPIC_ARN
-
-node scripts/aws-windows-jit-campaign.mjs kill-campaign \
-  --campaign-id "$windows_campaign" \
-  --confirm-campaign-id "$windows_campaign" \
-  --source-sha "$windows_source" \
-  --confirm-source-sha "$windows_source" \
-  --state-table "$windows_state_table" \
-  --confirm-state-table "$windows_state_table" \
-  --kill-switch-topic "$windows_kill_topic" \
-  --confirm-kill-switch-topic "$windows_kill_topic" \
-  --reason operator-kill
-```
+### Lower-level campaign and launch controllers
+
+`scripts/aws-windows-jit-campaign-core.mjs` owns the pure one-shot ledger
+contract used by the operator and launch controller. Arming creates `CONTROL`
+and `CAMPAIGN#<id>` with `attribute_not_exists` conditions, so DynamoDB refuses
+a second campaign in the same retained state table. There is deliberately no
+clear or re-arm operation.
+
+Every `scripts/aws-windows-jit-controller.mjs --execute` call must provide the
+same `--account-id`, `--campaign-id`, `--confirm-campaign-id`, `--state-table`,
+and `--confirm-state-table`. Before GitHub JIT material is created, the
+controller verifies the exact provider Budget/dimension filter and proves the
+global Budget kill sentinel absent. After the GitHub, AMI, active-instance,
+SSM, and EC2 DryRun checks pass, the controller
+atomically reserves one run. Duplicate run-attempt-qualification identities,
+source mismatch, expiry, `KILLED`, the sixth accepted instance, or a
+reservation that would exceed the USD 110 ceiling after combining the persisted
+fresh Cost Explorer baseline with all in-flight campaign reservations all fail
+closed in one DynamoDB transaction before `RunInstances`. AWS Budget alarms are
+defense in depth for delayed billing telemetry; the atomic ledger is the
+authoritative launch-time guard. The operator is the only supported mutation
+surface for campaign preparation and closeout; direct imports of the core are
+not operator authority.
 
 ## Phase 3 contract
 

package/docs/cli-reference.md

@@ -223,6 +223,160 @@ buildchain dev
 buildchain dev merge-queue --repository <owner/repo> --branch <dev/vN/vN.M> [--from-config | --workflow <required-workflow.yml>...] [--cwd <dir>] [--check-response-timeout-minutes <n>] [--max-entries-to-build <n>] [--apply]
 ```
 
+### `buildchain dev pr-admit`
+
+- Help: `buildchain dev pr-admit --help`
+- Canonical id: `dev`
+- Options: `--branch`, `--execute`, `--expected-head`, `--json`, `--output`, `--pull-request`, `--repository`
+- Syntax:
+
+```text
+buildchain dev pr-admit --repository <owner/repo> --branch <dev/vN/vN.M> --pull-request <n> --expected-head <sha> [--execute] [--output <file>] [--json]
+```
+
+### `buildchain dev proof classify`
+
+- Help: `buildchain dev proof classify --help`
+- Canonical id: `dev`
+- Options: `--json`, `--output`
+- Syntax:
+
+```text
+buildchain dev proof <source|verify-source|classify|replay|integration|verify-integration> [--output <file>] [--json]
+```
+
+### `buildchain dev proof integration`
+
+- Help: `buildchain dev proof integration --help`
+- Canonical id: `dev`
+- Options: `--json`, `--output`
+- Syntax:
+
+```text
+buildchain dev proof <source|verify-source|classify|replay|integration|verify-integration> [--output <file>] [--json]
+```
+
+### `buildchain dev proof replay`
+
+- Help: `buildchain dev proof replay --help`
+- Canonical id: `dev`
+- Options: `--json`, `--output`
+- Syntax:
+
+```text
+buildchain dev proof <source|verify-source|classify|replay|integration|verify-integration> [--output <file>] [--json]
+```
+
+### `buildchain dev proof source`
+
+- Help: `buildchain dev proof source --help`
+- Canonical id: `dev`
+- Options: `--json`, `--output`
+- Syntax:
+
+```text
+buildchain dev proof <source|verify-source|classify|replay|integration|verify-integration> [--output <file>] [--json]
+```
+
+### `buildchain dev proof verify-integration`
+
+- Help: `buildchain dev proof verify-integration --help`
+- Canonical id: `dev`
+- Options: `--json`, `--output`
+- Syntax:
+
+```text
+buildchain dev proof <source|verify-source|classify|replay|integration|verify-integration> [--output <file>] [--json]
+```
+
+### `buildchain dev proof verify-source`
+
+- Help: `buildchain dev proof verify-source --help`
+- Canonical id: `dev`
+- Options: `--json`, `--output`
+- Syntax:
+
+```text
+buildchain dev proof <source|verify-source|classify|replay|integration|verify-integration> [--output <file>] [--json]
+```
+
+### `buildchain dev warrant cancel-queued`
+
+- Help: `buildchain dev warrant cancel-queued --help`
+- Canonical id: `dev`
+- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`
+- Syntax:
+
+```text
+buildchain dev warrant <submit|select|heartbeat|recover|close|cancel-queued|observe> --repository <owner/repo> --branch <dev/vN/vN.M> [--execute] [--output <file>] [--json]
+```
+
+### `buildchain dev warrant close`
+
+- Help: `buildchain dev warrant close --help`
+- Canonical id: `dev`
+- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`
+- Syntax:
+
+```text
+buildchain dev warrant <submit|select|heartbeat|recover|close|cancel-queued|observe> --repository <owner/repo> --branch <dev/vN/vN.M> [--execute] [--output <file>] [--json]
+```
+
+### `buildchain dev warrant heartbeat`
+
+- Help: `buildchain dev warrant heartbeat --help`
+- Canonical id: `dev`
+- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`
+- Syntax:
+
+```text
+buildchain dev warrant <submit|select|heartbeat|recover|close|cancel-queued|observe> --repository <owner/repo> --branch <dev/vN/vN.M> [--execute] [--output <file>] [--json]
+```
+
+### `buildchain dev warrant observe`
+
+- Help: `buildchain dev warrant observe --help`
+- Canonical id: `dev`
+- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`
+- Syntax:
+
+```text
+buildchain dev warrant <submit|select|heartbeat|recover|close|cancel-queued|observe> --repository <owner/repo> --branch <dev/vN/vN.M> [--execute] [--output <file>] [--json]
+```
+
+### `buildchain dev warrant recover`
+
+- Help: `buildchain dev warrant recover --help`
+- Canonical id: `dev`
+- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`
+- Syntax:
+
+```text
+buildchain dev warrant <submit|select|heartbeat|recover|close|cancel-queued|observe> --repository <owner/repo> --branch <dev/vN/vN.M> [--execute] [--output <file>] [--json]
+```
+
+### `buildchain dev warrant select`
+
+- Help: `buildchain dev warrant select --help`
+- Canonical id: `dev`
+- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`
+- Syntax:
+
+```text
+buildchain dev warrant <submit|select|heartbeat|recover|close|cancel-queued|observe> --repository <owner/repo> --branch <dev/vN/vN.M> [--execute] [--output <file>] [--json]
+```
+
+### `buildchain dev warrant submit`
+
+- Help: `buildchain dev warrant submit --help`
+- Canonical id: `dev`
+- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`
+- Syntax:
+
+```text
+buildchain dev warrant <submit|select|heartbeat|recover|close|cancel-queued|observe> --repository <owner/repo> --branch <dev/vN/vN.M> [--execute] [--output <file>] [--json]
+```
+
 ## `diagnostics`
 
 ### `buildchain diagnostics`

package/docs/dev-alpha-candidate-patrol.md

@@ -8,12 +8,12 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: self-reviewed
-last_reviewed: 2026-08-03
+last_reviewed: 2026-08-04
 ai_provenance:
   model_family: GPT-5
   product: Codex
-  generated_at: 2026-07-29
-  visible_context: Existing Buildchain source locks, Kungfu exact-source Alpha preflight, Dev Patrol, protected auto-merge policy, repository release governance, and the consumer-owned settlement renderer threat model.
+  generated_at: 2026-08-04
+  visible_context: Existing Buildchain source locks, Kungfu exact-source Alpha preflight, Dev Patrol, cancelled duplicate runs, protected auto-merge policy, repository release governance, and the consumer-owned settlement renderer threat model.
   invisible_context_boundary: No credentials, private logs, or private configuration were used.
 ---
 
@@ -27,8 +27,10 @@ bounded development history from newest to oldest (stopping early at the Alpha
 head), and selects the newest commit that satisfies all of these conditions:
 
 - the source is strictly ahead of the recorded target head;
-- the latest completed Dev Patrol for that exact commit SHA succeeded;
-- the latest completed Alpha preflight for the same commit SHA succeeded; and
+- the latest completed, non-cancelled Dev Patrol for that exact commit SHA
+  succeeded;
+- the latest completed, non-cancelled Alpha preflight for the same commit SHA
+  succeeded; and
 - both runs are within the caller's evidence age limit.
 
 The selected commit can be behind the observed development head when newer
@@ -37,6 +39,12 @@ head, selected SHA, and count of skipped newer commits. This makes a slow native
 verification lane live under continuous development without silently treating
 an unqualified head as releasable.
 
+A cancelled workflow run carries no qualification verdict, so a newer
+cancelled duplicate does not erase the prior completed verdict for the same
+workflow and source SHA. Other non-success conclusions remain authoritative:
+a newer failed, timed-out, skipped, or otherwise non-successful completed run
+still excludes that SHA and forces the controller to fall back or fail closed.
+
 History discovery is bounded to the newest 1000 development commits. The
 controller then compares the selected SHA to the exact Alpha head before it can
 be eligible, so a bounded scan cannot turn a commit outside the promotion