@intentius/chant 0.124.62 → 0.124.64

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (262) hide show
  1. package/dist/cli/handlers/approve.d.ts +26 -0
  2. package/dist/cli/handlers/approve.d.ts.map +1 -1
  3. package/dist/cli/handlers/approve.js +167 -18
  4. package/dist/cli/handlers/plan.d.ts +10 -0
  5. package/dist/cli/handlers/plan.d.ts.map +1 -0
  6. package/dist/cli/handlers/plan.js +71 -0
  7. package/dist/cli/handlers/pr.d.ts.map +1 -1
  8. package/dist/cli/handlers/pr.js +2 -1
  9. package/dist/cli/handlers/release.d.ts +11 -7
  10. package/dist/cli/handlers/release.d.ts.map +1 -1
  11. package/dist/cli/handlers/release.js +93 -20
  12. package/dist/cli/main.d.ts.map +1 -1
  13. package/dist/cli/main.js +48 -7
  14. package/dist/cli/mcp/workspace-tools.d.ts.map +1 -1
  15. package/dist/cli/mcp/workspace-tools.js +2 -1
  16. package/dist/cli/parse-args.d.ts.map +1 -1
  17. package/dist/cli/parse-args.js +43 -0
  18. package/dist/cli/registry.d.ts +18 -2
  19. package/dist/cli/registry.d.ts.map +1 -1
  20. package/dist/config.d.ts +50 -0
  21. package/dist/config.d.ts.map +1 -1
  22. package/dist/config.js +1 -0
  23. package/dist/gate-decision.d.ts +1 -1
  24. package/dist/gate-decision.d.ts.map +1 -1
  25. package/dist/gate-decision.js +4 -2
  26. package/dist/gate-statement.schema.json +46 -0
  27. package/dist/lifecycle/__fixtures__/publish-fakes.d.ts +20 -0
  28. package/dist/lifecycle/__fixtures__/publish-fakes.d.ts.map +1 -1
  29. package/dist/lifecycle/__fixtures__/publish-fakes.js +119 -3
  30. package/dist/lifecycle/gate-ledger.d.ts +28 -5
  31. package/dist/lifecycle/gate-ledger.d.ts.map +1 -1
  32. package/dist/lifecycle/gate-ledger.js +6 -0
  33. package/dist/lifecycle/gate-seal.d.ts +59 -7
  34. package/dist/lifecycle/gate-seal.d.ts.map +1 -1
  35. package/dist/lifecycle/gate-seal.js +68 -15
  36. package/dist/lifecycle/gate-statement.d.ts +95 -0
  37. package/dist/lifecycle/gate-statement.d.ts.map +1 -0
  38. package/dist/lifecycle/gate-statement.js +110 -0
  39. package/dist/lifecycle/gate-webauthn.d.ts +79 -0
  40. package/dist/lifecycle/gate-webauthn.d.ts.map +1 -0
  41. package/dist/lifecycle/gate-webauthn.js +105 -0
  42. package/dist/lifecycle/git.d.ts +1 -1
  43. package/dist/lifecycle/git.d.ts.map +1 -1
  44. package/dist/lifecycle/git.js +24 -19
  45. package/dist/lifecycle/ledger-remote.d.ts +37 -0
  46. package/dist/lifecycle/ledger-remote.d.ts.map +1 -0
  47. package/dist/lifecycle/ledger-remote.js +42 -0
  48. package/dist/lifecycle/plan-stale.d.ts +76 -0
  49. package/dist/lifecycle/plan-stale.d.ts.map +1 -0
  50. package/dist/lifecycle/plan-stale.js +120 -0
  51. package/dist/lifecycle/publish-credentials.d.ts +1 -1
  52. package/dist/lifecycle/publish-credentials.d.ts.map +1 -1
  53. package/dist/lifecycle/publish-credentials.js +2 -0
  54. package/dist/lifecycle/publish-declaration.d.ts +107 -0
  55. package/dist/lifecycle/publish-declaration.d.ts.map +1 -1
  56. package/dist/lifecycle/publish-declaration.js +110 -1
  57. package/dist/lifecycle/publish-forge.d.ts +5 -1
  58. package/dist/lifecycle/publish-forge.d.ts.map +1 -1
  59. package/dist/lifecycle/publish-forge.js +13 -4
  60. package/dist/lifecycle/publish-git-ssh.d.ts +82 -0
  61. package/dist/lifecycle/publish-git-ssh.d.ts.map +1 -0
  62. package/dist/lifecycle/publish-git-ssh.js +180 -0
  63. package/dist/lifecycle/publish-github.d.ts +69 -0
  64. package/dist/lifecycle/publish-github.d.ts.map +1 -0
  65. package/dist/lifecycle/publish-github.js +153 -0
  66. package/dist/lifecycle/publish-homebrew.d.ts +77 -0
  67. package/dist/lifecycle/publish-homebrew.d.ts.map +1 -0
  68. package/dist/lifecycle/publish-homebrew.js +265 -0
  69. package/dist/lifecycle/publish-marketplace.d.ts +85 -0
  70. package/dist/lifecycle/publish-marketplace.d.ts.map +1 -0
  71. package/dist/lifecycle/publish-marketplace.js +398 -0
  72. package/dist/lifecycle/publish-targets.d.ts +6 -0
  73. package/dist/lifecycle/publish-targets.d.ts.map +1 -1
  74. package/dist/lifecycle/publish-targets.js +15 -0
  75. package/dist/lifecycle/publish-tauri.d.ts +61 -0
  76. package/dist/lifecycle/publish-tauri.d.ts.map +1 -0
  77. package/dist/lifecycle/publish-tauri.js +181 -0
  78. package/dist/lifecycle/release-cut.d.ts +51 -5
  79. package/dist/lifecycle/release-cut.d.ts.map +1 -1
  80. package/dist/lifecycle/release-cut.js +165 -16
  81. package/dist/lifecycle/release-publish.d.ts +18 -2
  82. package/dist/lifecycle/release-publish.d.ts.map +1 -1
  83. package/dist/lifecycle/release-publish.js +5 -0
  84. package/dist/lifecycle/release-revocation.d.ts +4 -3
  85. package/dist/lifecycle/release-revocation.d.ts.map +1 -1
  86. package/dist/lifecycle/release-revocation.js +5 -4
  87. package/dist/lifecycle/release-store.d.ts +32 -0
  88. package/dist/lifecycle/release-store.d.ts.map +1 -1
  89. package/dist/lifecycle/release-store.js +11 -0
  90. package/dist/lifecycle/snapshot-store.d.ts.map +1 -1
  91. package/dist/lifecycle/snapshot-store.js +17 -9
  92. package/dist/lifecycle/test-passkey.d.ts +25 -0
  93. package/dist/lifecycle/test-passkey.d.ts.map +1 -0
  94. package/dist/lifecycle/test-passkey.js +39 -0
  95. package/dist/notify.d.ts +23 -3
  96. package/dist/notify.d.ts.map +1 -1
  97. package/dist/notify.js +8 -2
  98. package/dist/notify.schema.json +12 -3
  99. package/dist/op/gate.d.ts +1 -1
  100. package/dist/op/gate.d.ts.map +1 -1
  101. package/dist/op/gate.js +2 -1
  102. package/dist/pr-forge.d.ts +20 -0
  103. package/dist/pr-forge.d.ts.map +1 -1
  104. package/dist/pr-forge.js +87 -8
  105. package/dist/release-floors.d.ts +1 -1
  106. package/dist/release-floors.js +1 -1
  107. package/dist/wave-runtime.mjs +333 -331
  108. package/dist/workspace/ci-builds.d.ts +21 -0
  109. package/dist/workspace/ci-builds.d.ts.map +1 -1
  110. package/dist/workspace/ci-builds.js +14 -0
  111. package/dist/workspace/ci-green.d.ts +45 -2
  112. package/dist/workspace/ci-green.d.ts.map +1 -1
  113. package/dist/workspace/ci-green.js +123 -5
  114. package/dist/workspace/ci-quarantine-report.d.ts +80 -0
  115. package/dist/workspace/ci-quarantine-report.d.ts.map +1 -0
  116. package/dist/workspace/ci-quarantine-report.js +204 -0
  117. package/dist/workspace/ci-quarantine.d.ts +73 -0
  118. package/dist/workspace/ci-quarantine.d.ts.map +1 -0
  119. package/dist/workspace/ci-quarantine.js +170 -0
  120. package/dist/workspace/ci-serve.d.ts.map +1 -1
  121. package/dist/workspace/ci-serve.js +7 -4
  122. package/dist/workspace/class-data.d.ts +3 -1
  123. package/dist/workspace/class-data.d.ts.map +1 -1
  124. package/dist/workspace/class-data.js +4 -1
  125. package/dist/workspace/declaration.d.ts +45 -2
  126. package/dist/workspace/declaration.d.ts.map +1 -1
  127. package/dist/workspace/declaration.js +45 -2
  128. package/dist/workspace/declaration.schema.json +51 -3
  129. package/dist/workspace/forge-work.d.ts +76 -0
  130. package/dist/workspace/forge-work.d.ts.map +1 -0
  131. package/dist/workspace/forge-work.js +160 -0
  132. package/dist/workspace/identity-gate-rule.d.ts +3 -2
  133. package/dist/workspace/identity-gate-rule.d.ts.map +1 -1
  134. package/dist/workspace/identity-gate-rule.js +5 -7
  135. package/dist/workspace/identity.d.ts +3 -2
  136. package/dist/workspace/identity.d.ts.map +1 -1
  137. package/dist/workspace/identity.js +6 -3
  138. package/dist/workspace/intent-cli.d.ts +3 -2
  139. package/dist/workspace/intent-cli.d.ts.map +1 -1
  140. package/dist/workspace/intent-cli.js +26 -5
  141. package/dist/workspace/intent-record.d.ts +3 -0
  142. package/dist/workspace/intent-record.d.ts.map +1 -1
  143. package/dist/workspace/intent-record.schema.json +32 -0
  144. package/dist/workspace/intent.d.ts +9 -0
  145. package/dist/workspace/intent.d.ts.map +1 -1
  146. package/dist/workspace/intent.js +2 -0
  147. package/dist/workspace/intent.schema.json +32 -0
  148. package/dist/workspace/kind-readers.d.ts.map +1 -1
  149. package/dist/workspace/kind-readers.js +2 -1
  150. package/dist/workspace/kinds.d.ts +6 -1
  151. package/dist/workspace/kinds.d.ts.map +1 -1
  152. package/dist/workspace/kinds.js +8 -3
  153. package/dist/workspace/plan-stale.schema.json +286 -0
  154. package/dist/workspace/release-candidates.d.ts +42 -7
  155. package/dist/workspace/release-candidates.d.ts.map +1 -1
  156. package/dist/workspace/release-candidates.js +64 -23
  157. package/dist/workspace/release-candidates.schema.json +55 -2
  158. package/dist/workspace/releases.schema.json +47 -0
  159. package/dist/workspace/trust/policy.d.ts +10 -0
  160. package/dist/workspace/trust/policy.d.ts.map +1 -1
  161. package/dist/workspace/trust/policy.js +19 -1
  162. package/dist/workspace/trust/run-commits.d.ts.map +1 -1
  163. package/dist/workspace/trust/run-commits.js +2 -1
  164. package/dist/workspace/trust/seal.d.ts.map +1 -1
  165. package/dist/workspace/trust/seal.js +34 -3
  166. package/dist/workspace/trust/trust-files.d.ts.map +1 -1
  167. package/dist/workspace/trust/trust-files.js +6 -1
  168. package/package.json +2 -1
  169. package/src/cli/handlers/approve-external-signature.test.ts +328 -0
  170. package/src/cli/handlers/approve.ts +206 -18
  171. package/src/cli/handlers/plan.ts +74 -0
  172. package/src/cli/handlers/pr.ts +2 -1
  173. package/src/cli/handlers/release.ts +84 -20
  174. package/src/cli/main.ts +48 -7
  175. package/src/cli/mcp/workspace-tools.ts +2 -1
  176. package/src/cli/parse-args.ts +33 -0
  177. package/src/cli/registry.ts +18 -2
  178. package/src/config.ts +8 -0
  179. package/src/gate-decision-bundle.test.ts +4 -2
  180. package/src/gate-decision.ts +11 -2
  181. package/src/gate-statement.schema.json +46 -0
  182. package/src/lifecycle/__fixtures__/publish-fakes.ts +125 -5
  183. package/src/lifecycle/gate-ledger.ts +34 -5
  184. package/src/lifecycle/gate-seal.ts +86 -15
  185. package/src/lifecycle/gate-statement.ts +144 -0
  186. package/src/lifecycle/gate-webauthn.test.ts +77 -0
  187. package/src/lifecycle/gate-webauthn.ts +133 -0
  188. package/src/lifecycle/git.ts +23 -19
  189. package/src/lifecycle/ledger-remote.test.ts +183 -0
  190. package/src/lifecycle/ledger-remote.ts +46 -0
  191. package/src/lifecycle/plan-stale.test.ts +149 -0
  192. package/src/lifecycle/plan-stale.ts +172 -0
  193. package/src/lifecycle/publish-credentials.ts +2 -0
  194. package/src/lifecycle/publish-declaration.ts +116 -1
  195. package/src/lifecycle/publish-forge.ts +14 -4
  196. package/src/lifecycle/publish-git-ssh.ts +202 -0
  197. package/src/lifecycle/publish-github.ts +174 -0
  198. package/src/lifecycle/publish-homebrew.test.ts +358 -0
  199. package/src/lifecycle/publish-homebrew.ts +283 -0
  200. package/src/lifecycle/publish-marketplace.test.ts +406 -0
  201. package/src/lifecycle/publish-marketplace.ts +421 -0
  202. package/src/lifecycle/publish-resume.test.ts +40 -0
  203. package/src/lifecycle/publish-target-context.test.ts +2 -2
  204. package/src/lifecycle/publish-targets.test.ts +23 -0
  205. package/src/lifecycle/publish-targets.ts +15 -0
  206. package/src/lifecycle/publish-tauri.test.ts +163 -0
  207. package/src/lifecycle/publish-tauri.ts +198 -0
  208. package/src/lifecycle/release-cut-lane.test.ts +177 -0
  209. package/src/lifecycle/release-cut-override.test.ts +213 -0
  210. package/src/lifecycle/release-cut.ts +198 -17
  211. package/src/lifecycle/release-publish.ts +23 -3
  212. package/src/lifecycle/release-revocation.ts +5 -4
  213. package/src/lifecycle/release-store.ts +44 -0
  214. package/src/lifecycle/snapshot-store.ts +16 -9
  215. package/src/lifecycle/test-passkey.ts +55 -0
  216. package/src/notify-bundle.test.ts +3 -1
  217. package/src/notify.schema.json +12 -3
  218. package/src/notify.ts +20 -3
  219. package/src/op/gate.ts +2 -1
  220. package/src/override-gate-bundle.test.ts +2 -0
  221. package/src/pr-forge-bundle.test.ts +2 -2
  222. package/src/pr-forge.test.ts +38 -0
  223. package/src/pr-forge.ts +93 -11
  224. package/src/pr-requires.test.ts +9 -0
  225. package/src/release-floors.ts +1 -1
  226. package/src/stage-hooks-bundle.test.ts +2 -0
  227. package/src/wave-runtime-bundle.test.ts +3 -2
  228. package/src/workspace/ci-builds.ts +27 -0
  229. package/src/workspace/ci-green-stale.test.ts +193 -0
  230. package/src/workspace/ci-green.ts +137 -6
  231. package/src/workspace/ci-quarantine-report.test.ts +145 -0
  232. package/src/workspace/ci-quarantine-report.ts +234 -0
  233. package/src/workspace/ci-quarantine.test.ts +160 -0
  234. package/src/workspace/ci-quarantine.ts +188 -0
  235. package/src/workspace/ci-serve.ts +7 -4
  236. package/src/workspace/class-data.ts +5 -1
  237. package/src/workspace/declaration.schema.json +51 -3
  238. package/src/workspace/declaration.test.ts +1 -0
  239. package/src/workspace/declaration.ts +88 -5
  240. package/src/workspace/forge-work.test.ts +143 -0
  241. package/src/workspace/forge-work.ts +195 -0
  242. package/src/workspace/identity-gate-rule.ts +6 -8
  243. package/src/workspace/identity.ts +6 -3
  244. package/src/workspace/intent-cli.ts +24 -5
  245. package/src/workspace/intent-record.schema.json +32 -0
  246. package/src/workspace/intent-record.ts +3 -0
  247. package/src/workspace/intent.schema.json +32 -0
  248. package/src/workspace/intent.ts +9 -0
  249. package/src/workspace/kind-readers.ts +2 -1
  250. package/src/workspace/kinds.test.ts +13 -0
  251. package/src/workspace/kinds.ts +12 -3
  252. package/src/workspace/plan-stale.schema.json +286 -0
  253. package/src/workspace/release-candidates.schema.json +55 -2
  254. package/src/workspace/release-candidates.test.ts +77 -4
  255. package/src/workspace/release-candidates.ts +80 -23
  256. package/src/workspace/releases.schema.json +47 -0
  257. package/src/workspace/trust/gate-seal.test.ts +44 -0
  258. package/src/workspace/trust/policy.ts +24 -1
  259. package/src/workspace/trust/run-commits.ts +2 -1
  260. package/src/workspace/trust/seal.ts +35 -3
  261. package/src/workspace/trust/trust-files.test.ts +5 -0
  262. package/src/workspace/trust/trust-files.ts +15 -1
@@ -27,6 +27,12 @@ import { PR_GATE_OP } from "../../pr-loop";
27
27
  import { pushLifecycleReport, requireLifecycleLedger } from "../../lifecycle/git";
28
28
  import { LIFECYCLE_LOCAL_NOTE, isLifecycleLocalNote } from "../../lifecycle/local-note";
29
29
  import { ledgerRecordingOff, NO_RECORD_ENV } from "../../lifecycle/no-record";
30
+ import { checkGateSignature, gateSealPayload, gateSealVersion, WEBAUTHN_SEAL_KIND, type SealedGateApproval } from "../../lifecycle/gate-seal";
31
+ import { gateBindingProblem, gateStatement, readExternalSignature, type GateStatement } from "../../lifecycle/gate-statement";
32
+ import type { GateApprovalSeal } from "../../lifecycle/gate-ledger";
33
+ import type { TrustPolicy } from "../../workspace/trust/policy";
34
+ import { readFileSync } from "node:fs";
35
+ import { resolve as resolvePath } from "node:path";
30
36
  import { formatError, formatWarning, formatSuccess, formatInfo } from "../format";
31
37
  import type { CommandContext } from "../registry";
32
38
 
@@ -158,12 +164,43 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
158
164
  // has applied since #2126 (`../handlers/run.ts`'s `runOpApprove`). Reading
159
165
  // only `--actor` here meant every README that teaches `--approver you`
160
166
  // recorded the shell user instead (#2192).
167
+ // #4646: the statement for a signature made elsewhere, on stdout, with nothing recorded.
168
+ if (ctx.args.statement) {
169
+ if (ctx.args.sign !== undefined || ctx.args.signature !== undefined) {
170
+ console.error(formatError({ message: "--statement prints what to sign and records nothing, so it takes neither --sign nor --signature" }));
171
+ return 1;
172
+ }
173
+ const shared: GateApprovalOptions = {
174
+ actor: ctx.args.approver ?? ctx.args.actor,
175
+ ...(ctx.args.plan !== undefined ? { plan: ctx.args.plan } : {}),
176
+ ...(ctx.args.env !== undefined ? { environment: ctx.args.env } : {}),
177
+ ...(ctx.args.relayedBy !== undefined ? { relayedBy: ctx.args.relayedBy } : {}),
178
+ ...(ctx.args.at !== undefined ? { at: ctx.args.at } : {}),
179
+ ...(ctx.args.binding !== undefined ? { binding: ctx.args.binding } : {}),
180
+ allowSameOrigin: ctx.args.allowSameOrigin,
181
+ };
182
+ const statement = await gateApprovalStatement(opName, gate, shared);
183
+ if (!statement) return 1;
184
+ console.log(JSON.stringify(statement, null, 2));
185
+ console.error(formatInfo(
186
+ `Have ${statement.resolvedBy} sign these bytes (an ssh key in the ${statement.namespace} namespace, or a passkey with challenge ${statement.challenge}), ` +
187
+ `then record it: chant approve ${opName} ${gate} --actor ${statement.resolvedBy}` +
188
+ (statement.relayedBy !== null ? ` --relayed-by ${statement.relayedBy}` : "") +
189
+ (statement.planDigest !== null ? ` --plan ${statement.planDigest}` : "") +
190
+ (statement.environment !== null ? ` --env ${statement.environment}` : "") +
191
+ (statement.binding !== null ? ` --binding ${shellQuote(statement.binding)}` : "") +
192
+ ` --at ${statement.timestamp} --signature <file>`,
193
+ ));
194
+ return 0;
195
+ }
196
+
161
197
  // #4575: a person at a terminal sees the plan and types the target's name
162
198
  // first, and the approval binds the digest they were shown. --yes, --json,
163
199
  // CI and no terminal record as before.
164
200
  let plan = ctx.args.plan;
165
201
  const confirm = await import("./approve-confirm");
166
- if (await confirm.interactiveApproval(ctx.args)) {
202
+ // #4646: an approval signed elsewhere was confirmed where it was signed.
203
+ if (ctx.args.signature === undefined && (await confirm.interactiveApproval(ctx.args))) {
167
204
  const answered = await confirm.confirmApproval(opName, gate, {
168
205
  ...(plan !== undefined ? { plan } : {}),
169
206
  ...(ctx.args.env !== undefined ? { environment: ctx.args.env } : {}),
@@ -181,6 +218,9 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
181
218
  ...(ctx.args.roles ? { roles: ctx.args.roles } : {}),
182
219
  ...(ctx.args.agent ? { agent: true } : {}),
183
220
  ...(ctx.args.sign !== undefined ? { sign: ctx.args.sign } : {}),
221
+ ...(ctx.args.signature !== undefined ? { signature: ctx.args.signature } : {}),
222
+ ...(ctx.args.at !== undefined ? { at: ctx.args.at } : {}),
223
+ ...(ctx.args.binding !== undefined ? { binding: ctx.args.binding } : {}),
184
224
  ...(ctx.args.relayedBy !== undefined ? { relayedBy: ctx.args.relayedBy } : {}),
185
225
  });
186
226
  if (!outcome.ok) return 1;
@@ -267,6 +307,23 @@ export interface GateApprovalOptions {
267
307
  * the declaration's `identity.gates` names counts only sealed approvals.
268
308
  */
269
309
  sign?: string | true;
310
+ /**
311
+ * `--signature <file>` (#4646): a signature made outside chant over the
312
+ * approval's statement (`--statement`), an armored ssh signature or a
313
+ * WebAuthn assertion in JSON; `-` reads it from stdin. Checked against the
314
+ * keys and passkeys listed at base for the approver, and kept as the seal.
315
+ */
316
+ signature?: string;
317
+ /** `--at <timestamp>` (#4646): the statement's time, which `--statement` fixes and `--signature` records. */
318
+ at?: string;
319
+ /**
320
+ * `--binding <text>` (#4697): a line the relay sets for the approver's
321
+ * signature to cover as well, such as a platform's deploy id and an
322
+ * expiry. Signed last (seal version 3) and recorded as `binding`. It goes
323
+ * with `--statement`, `--signature` or `--sign`, and must be the same on
324
+ * `--statement` and `--signature`.
325
+ */
326
+ binding?: string;
270
327
  /** Where the workspace and the key file are looked up from. Defaults to the process's directory. */
271
328
  cwd?: string;
272
329
  /** Replaces the lexicon evaluator a gate policy is loaded from. For tests. */
@@ -337,8 +394,30 @@ export async function recordGateApproval(
337
394
  gate: string,
338
395
  opts: GateApprovalOptions,
339
396
  ): Promise<GateApprovalOutcome> {
397
+ const r = await approveGate(opName, gate, opts, false);
398
+ return "statement" in r ? { ok: false } : r;
399
+ }
400
+
401
+ /**
402
+ * The statement an approval of this gate would sign (#4646), for a signature
403
+ * made outside chant: what `chant approve <op> <gate> --statement` prints.
404
+ * It runs every check {@link recordGateApproval} runs before signing, with
405
+ * the same options, and writes nothing. Null when a check refuses, which it
406
+ * prints.
407
+ */
408
+ export async function gateApprovalStatement(opName: string, gate: string, opts: GateApprovalOptions): Promise<GateStatement | null> {
409
+ const r = await approveGate(opName, gate, opts, true);
410
+ return "statement" in r ? r.statement : null;
411
+ }
412
+
413
+ async function approveGate(
414
+ opName: string,
415
+ gate: string,
416
+ opts: GateApprovalOptions,
417
+ statementOnly: boolean,
418
+ ): Promise<GateApprovalOutcome | { statement: GateStatement }> {
340
419
  // #3955: with recording off the approval would be dropped with the process.
341
- if (ledgerRecordingOff()) {
420
+ if (!statementOnly && ledgerRecordingOff()) {
342
421
  console.error(formatError({
343
422
  message: `Cannot record the approval of "${gate}": ${NO_RECORD_ENV} is set, so nothing is written to chant/lifecycle`,
344
423
  hint: `Unset ${NO_RECORD_ENV} to approve the gate.`,
@@ -557,36 +636,89 @@ export async function recordGateApproval(
557
636
  }));
558
637
  return { ok: false };
559
638
  }
639
+ // #4646: --statement prints the bytes a signature made elsewhere signs, at
640
+ // a time it fixes; --signature records that signature with the same time.
641
+ const refuse = (message: string, hint?: string) => {
642
+ console.error(formatError({ message: `Gate "${gate}" on "${opName}" was not approved: ${message}`, ...(hint ? { hint } : {}) }));
643
+ return { ok: false } as const;
644
+ };
645
+ if (opts.signature !== undefined && opts.sign !== undefined) {
646
+ return refuse("--sign signs here and --signature brings a signature made elsewhere; pass one of them");
647
+ }
648
+ if (opts.at !== undefined && !statementOnly && opts.signature === undefined) {
649
+ return refuse("--at sets the time of a statement signed elsewhere, so it goes with --statement or --signature");
650
+ }
651
+ if (opts.signature !== undefined && opts.at === undefined) {
652
+ return refuse(
653
+ "--signature needs --at <timestamp>, the statement's time, since the signature covers it",
654
+ `Pass the timestamp \`chant approve ${opName} ${gate} --statement\` printed.`,
655
+ );
656
+ }
657
+ if (opts.binding !== undefined) {
658
+ if (!statementOnly && opts.signature === undefined && opts.sign === undefined) {
659
+ return refuse("--binding is a line the approver's signature covers, so it goes with --statement, --signature or --sign");
660
+ }
661
+ const problem = gateBindingProblem(opts.binding);
662
+ if (problem !== null) return refuse(`--binding takes one line of printable text, and ${problem}`);
663
+ }
664
+ let timestamp = new Date().toISOString();
665
+ if (opts.at !== undefined) {
666
+ const at = Date.parse(opts.at);
667
+ if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(opts.at) || Number.isNaN(at) || new Date(at).toISOString() !== opts.at) {
668
+ return refuse(`--at takes a UTC time as chant writes one, such as ${timestamp}, not ${JSON.stringify(opts.at)}`);
669
+ }
670
+ if (at > Date.now() + AT_SKEW_MS) return refuse(`--at ${opts.at} is in the future`);
671
+ if (standing && opts.at < standing.timestamp) {
672
+ return refuse(
673
+ `--at ${opts.at} is before the pending fact it answers (${standing.timestamp}), and a run counts only approvals newer than that`,
674
+ `Take a fresh statement: chant approve ${opName} ${gate} --statement.`,
675
+ );
676
+ }
677
+ timestamp = opts.at;
678
+ }
679
+ const sealed: SealedGateApproval = {
680
+ op: opName,
681
+ gate,
682
+ ...(environment !== undefined ? { environment } : {}),
683
+ ...(planDigest !== undefined ? { planDigest } : {}),
684
+ resolvedBy,
685
+ ...(relayedBy ? { relayedBy } : {}),
686
+ timestamp,
687
+ ...(checkpointDigest !== undefined ? { checkpointDigest } : {}),
688
+ ...(opts.binding !== undefined ? { binding: opts.binding } : {}),
689
+ };
690
+ if (statementOnly) {
691
+ const { CHANT_VERSION } = await import("../../chant-version");
692
+ return { statement: gateStatement(sealed, CHANT_VERSION) };
693
+ }
694
+
560
695
  const rule = identity.gateAdmissionFrom(scope, gate);
561
- if (rule && opts.sign === undefined) {
696
+ if (rule && opts.sign === undefined && opts.signature === undefined) {
562
697
  console.error(formatError({
563
698
  message:
564
699
  `Gate "${gate}" needs a signed approval: chant.workspace.json at base names it in identity.gates` +
565
700
  (rule.requirement.class !== null ? `, from the class ${rule.requirement.class}` : "") +
566
701
  `, and this approval is not signed`,
567
- hint: `chant approve ${opName} ${gate} --actor <principal> --sign [<key file>], with a key ${scope.policy.signersPath} at base lists for that principal.`,
702
+ hint:
703
+ `chant approve ${opName} ${gate} --actor <principal> --sign [<key file>], with a key ${scope.policy.signersPath} at base lists for that principal, ` +
704
+ `or --signature <file> --at <timestamp> with a signature made elsewhere over the statement --statement prints.`,
568
705
  }));
569
706
  return { ok: false };
570
707
  }
571
- const timestamp = new Date().toISOString();
572
708
  let seal: GateResolutionRecord["seal"];
709
+ if (opts.signature !== undefined) {
710
+ const made = externalSeal(opts.signature, sealed, scope.policy, cwd);
711
+ if ("refused" in made) return refuse(made.refused);
712
+ seal = made.seal;
713
+ }
573
714
  if (opts.sign !== undefined) {
574
715
  const { resolveSigningKey, sealGateApproval, gateSealVersion, SealError } = await import("../../workspace/trust/seal");
575
716
  try {
576
717
  const key = resolveSigningKey(opts.sign, cwd);
577
718
  try {
578
- const sealed = {
579
- op: opName,
580
- gate,
581
- ...(environment !== undefined ? { environment } : {}),
582
- ...(planDigest !== undefined ? { planDigest } : {}),
583
- resolvedBy,
584
- ...(relayedBy ? { relayedBy } : {}),
585
- timestamp,
586
- ...(checkpointDigest !== undefined ? { checkpointDigest } : {}),
587
- };
588
- // #3947: a seal over a checkpoint digest is seal version 2.
589
- seal = { ...sealGateApproval(key.file, sealed), ...(gateSealVersion(sealed) === 2 ? { version: 2 as const } : {}) };
719
+ // #3947, #4697: a seal over a checkpoint digest is seal version 2, and one over a binding 3.
720
+ const version = gateSealVersion(sealed);
721
+ seal = { ...sealGateApproval(key.file, sealed), ...(version !== 1 ? { version } : {}) };
590
722
  } finally {
591
723
  key.cleanup();
592
724
  }
@@ -606,6 +738,7 @@ export async function recordGateApproval(
606
738
  ...(relayedBy ? { relayedBy } : {}),
607
739
  timestamp,
608
740
  ...(checkpointDigest !== undefined ? { checkpointDigest } : {}),
741
+ ...(opts.binding !== undefined ? { binding: opts.binding } : {}),
609
742
  seal,
610
743
  });
611
744
  if (why !== null) {
@@ -636,6 +769,7 @@ export async function recordGateApproval(
636
769
  ...(relayedBy ? { relayedBy } : {}),
637
770
  timestamp,
638
771
  ...(checkpointDigest !== undefined ? { checkpointDigest } : {}),
772
+ ...(opts.binding !== undefined ? { binding: opts.binding } : {}),
639
773
  ...(seal ? { seal } : {}),
640
774
  }).roles;
641
775
  let policyDecision: GatePolicyDecision | undefined;
@@ -685,6 +819,7 @@ export async function recordGateApproval(
685
819
  ...(url ? { url } : {}),
686
820
  ...(planDigest !== undefined ? { planDigest } : {}),
687
821
  ...(checkpointDigest !== undefined ? { checkpointDigest } : {}),
822
+ ...(opts.binding !== undefined ? { binding: opts.binding } : {}),
688
823
  ...(environment !== undefined ? { environment } : {}),
689
824
  ...(releaseDigest !== undefined ? { releaseDigest } : {}),
690
825
  ...(changeSet !== undefined ? { changeSet } : {}),
@@ -704,9 +839,10 @@ export async function recordGateApproval(
704
839
  (record.relayedBy ? `, relayed by ${record.relayedBy},` : "") +
705
840
  ` at ${record.timestamp}` +
706
841
  (record.url ? ` (${record.url})` : "") +
707
- (record.seal ? `, signed with ${record.seal.key}` : "") +
842
+ (record.seal ? `, signed with ${record.seal.kind === WEBAUTHN_SEAL_KIND ? "passkey " : ""}${record.seal.key}` : "") +
708
843
  push.suffix,
709
844
  ));
845
+ if (record.binding !== undefined) console.error(formatInfo(`The signature also binds ${JSON.stringify(record.binding)} (--binding).`));
710
846
  if (record.planDigest) {
711
847
  console.error(formatInfo(
712
848
  `This approves the plan ${record.planDigest}` +
@@ -736,6 +872,58 @@ export async function recordGateApproval(
736
872
  return { ok: true, record, pushed: push.pushed };
737
873
  }
738
874
 
875
+ /** How far in the future `--at` may be (#4646), for a clock that runs a little ahead of this one. */
876
+ const AT_SKEW_MS = 5 * 60 * 1000;
877
+
878
+ /**
879
+ * The seal for a signature made outside chant (#4646): the file `--signature`
880
+ * names (`-` for stdin), read as an armored ssh signature or a WebAuthn
881
+ * assertion, and checked over `sealed`'s statement against the keys and
882
+ * passkeys listed at base for the approver. A signature nothing at base
883
+ * vouches for is refused rather than recorded.
884
+ */
885
+ function externalSeal(
886
+ from: string,
887
+ sealed: SealedGateApproval,
888
+ policy: TrustPolicy,
889
+ cwd: string,
890
+ ): { seal: GateApprovalSeal } | { refused: string } {
891
+ let text: string;
892
+ try {
893
+ text = from === "-" ? readFileSync(0, "utf-8") : readFileSync(resolvePath(cwd, from), "utf-8");
894
+ } catch (err) {
895
+ return { refused: `--signature ${from} can't be read: ${err instanceof Error ? err.message : String(err)}` };
896
+ }
897
+ const sig = readExternalSignature(text);
898
+ if ("problem" in sig) return { refused: `--signature ${from}: ${sig.problem}` };
899
+ const candidate: GateApprovalSeal =
900
+ sig.kind === "ssh"
901
+ ? { signer: sealed.resolvedBy, key: "", signature: sig.signature }
902
+ : {
903
+ kind: WEBAUTHN_SEAL_KIND,
904
+ signer: sealed.resolvedBy,
905
+ key: sig.assertion.id,
906
+ signature: sig.assertion.signature,
907
+ clientDataJSON: sig.assertion.clientDataJSON,
908
+ authenticatorData: sig.assertion.authenticatorData,
909
+ };
910
+ const r = checkGateSignature(policy, sealed.resolvedBy, candidate as unknown as { signature: string } & Record<string, unknown>, gateSealPayload(sealed));
911
+ if (!r.ok) {
912
+ return {
913
+ refused: r.unlisted
914
+ ? `${sealed.resolvedBy} has no ${sig.kind === "ssh" ? `key in ${policy.signersPath}` : "passkey in .chant/trust.json"} at base, so a signature made elsewhere can't be checked`
915
+ : `the ${sig.kind === "ssh" ? "ssh signature" : "passkey's assertion"} does not verify for ${sealed.resolvedBy} over this approval's statement: ${r.reason}`,
916
+ };
917
+ }
918
+ const version = gateSealVersion(sealed);
919
+ return { seal: { ...candidate, key: r.key, ...(version !== 1 ? { version } : {}) } };
920
+ }
921
+
922
+ /** `text` quoted for a POSIX shell, for a command line a hint prints. */
923
+ function shellQuote(text: string): string {
924
+ return /^[\w@%+=:,./-]+$/.test(text) ? text : `'${text.replace(/'/g, `'\\''`)}'`;
925
+ }
926
+
739
927
  /**
740
928
  * What a just-recorded approval did to a gate with an `approval` block
741
929
  * (#2508): the policy's decision and whether it binds, then the quorum count
@@ -0,0 +1,74 @@
1
+ /**
2
+ * `chant plan stale <digest> [--member <name>] [--json]` (#4648): whether
3
+ * anything applied to a plan's targets after the plan was recorded, and
4
+ * which applies. The rule is `../../lifecycle/plan-stale.ts`; the ledgers
5
+ * are read as `chant ledger` reads them (`./query.ts` {@link queryLedgers}),
6
+ * from the local `chant/lifecycle` branch. It never fetches and never writes,
7
+ * so a platform can call it before it asks a person to approve. Exit 0 when
8
+ * the plan is current, 2 when it is stale, 1 when no pending gate fact
9
+ * records the digest or the ledger can't be read.
10
+ */
11
+ import { execFileSync } from "node:child_process";
12
+ import { resolve } from "node:path";
13
+ import { formatError } from "../format";
14
+ import type { CommandContext } from "../registry";
15
+ import type { PlanStaleDocument } from "../../lifecycle/plan-stale";
16
+ import { queryLedgers } from "./query";
17
+
18
+ const USAGE = "chant plan stale <digest> [--member <name>] [--json]";
19
+
20
+ /** The `plan-stale` document for `digest`, read from the ledgers at `cwd`: every member's, or the ones `members` names. */
21
+ export async function planStaleDocument(req: { cwd: string; digest: string; members?: readonly string[] }): Promise<PlanStaleDocument> {
22
+ const { planStaleness, planStaleHead } = await import("../../lifecycle/plan-stale");
23
+ const { readerVersion } = await import("../../workspace/declaration");
24
+ const head = planStaleHead(readerVersion());
25
+ try {
26
+ execFileSync("git", ["rev-parse", "--git-dir"], { cwd: req.cwd, stdio: "ignore" });
27
+ } catch {
28
+ return { ...head, error: { code: "not-a-git-repository", message: "plans are read from the chant/lifecycle branch, and this directory is not in a git repository" } };
29
+ }
30
+ const { loadQueryData } = await import("../../lifecycle/query");
31
+ try {
32
+ // No snapshot is read: an empty snapshot port stands in, so the snapshot files on the branch are skipped too.
33
+ const none = { read: async () => null, list: async () => [], trees: async () => [] };
34
+ const ledgers = (await queryLedgers(req.cwd, req.members)).map((l) => ({ ...l, snapshots: none }));
35
+ return planStaleness((await loadQueryData(ledgers)).data, req.digest, readerVersion());
36
+ } catch (err) {
37
+ return { ...head, error: { code: "ledger-unreadable", message: `reading the ledger failed: ${err instanceof Error ? err.message : String(err)}` } };
38
+ }
39
+ }
40
+
41
+ export async function runPlanStale(ctx: CommandContext): Promise<number> {
42
+ const { args } = ctx;
43
+ const digest = args.extraPositional;
44
+ if (!digest || digest.startsWith("-")) {
45
+ console.error(formatError({ message: "plan stale needs the plan digest a gate's pending fact records", hint: USAGE }));
46
+ return 1;
47
+ }
48
+ const doc = await planStaleDocument({ cwd: resolve("."), digest, members: args.members });
49
+ if (args.json) {
50
+ console.log(JSON.stringify(doc, null, 2));
51
+ return "error" in doc || doc.plan === null ? 1 : doc.stale ? 2 : 0;
52
+ }
53
+ if ("error" in doc) {
54
+ console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));
55
+ return 1;
56
+ }
57
+ if (doc.plan === null) {
58
+ console.error(formatError({ message: `no pending gate fact records the plan ${digest}`, hint: "Fetch chant/lifecycle first if the run that made the plan ran elsewhere: git fetch origin chant/lifecycle:chant/lifecycle" }));
59
+ return 1;
60
+ }
61
+ const where = doc.plan.targets.map((t) => `${t.member ? `${t.member}/` : ""}${t.op} at ${t.gate}${t.environment ? ` in ${t.environment}` : ""}`).join(", ");
62
+ console.log(`Plan ${digest}, recorded ${doc.plan.recordedAt} for ${where}.`);
63
+ if (!doc.stale) {
64
+ console.log("Nothing has applied to its targets since.");
65
+ return 0;
66
+ }
67
+ console.log(`Stale: ${doc.applies.length} ${doc.applies.length === 1 ? "apply" : "applies"} since.`);
68
+ for (const a of doc.applies) {
69
+ const what = a.source === "deploys" ? `deploy of ${a.component} to ${a.environment}` : `apply under ${a.op}/${a.gate} of ${a.planDigest}`;
70
+ const who = [a.actor ? `by ${a.actor}` : null, a.approvedBy ? `approved by ${a.approvedBy}` : null, a.runId ? `run ${a.runId}` : null].filter(Boolean).join(", ");
71
+ console.log(` ${a.at} ${what}${who ? ` (${who})` : ""}${a.result ? `: ${a.result}` : ""}`);
72
+ }
73
+ return 2;
74
+ }
@@ -1496,8 +1496,9 @@ async function beforeMergeChecks(ctx: CommandContext): Promise<PrBeforeMerge | n
1496
1496
  );
1497
1497
  }
1498
1498
  // The apply's own statuses never hold it back: chant ci run's, and the report's.
1499
+ // Nor does the plan's: a policy denial fails it, and the denial is only recorded when the apply judges it (plywood#66).
1499
1500
  // #4550: under a product's words its own prefix too.
1500
- const ignore = [...new Set([productContext(activeProductWords(), gate), productContext(activeProductWords(), PR_APPLY_GATE), `chant/${gate}`, `chant/${PR_APPLY_GATE}`, prStatusContext("apply", member)])];
1501
+ const ignore = [...new Set([productContext(activeProductWords(), gate), productContext(activeProductWords(), PR_APPLY_GATE), `chant/${gate}`, `chant/${PR_APPLY_GATE}`, prStatusContext("apply", member), prStatusContext("plan"), `${prStatusContext("plan")}/`])];
1501
1502
  // ws-106 gives the declaration no way to leave a check out, so with no --requires all four are asked (#4336, #4607).
1502
1503
  const requires = await checkPrRequires(forge, args.pr, head, { ignore, ...(only ? { only: only.checks } : {}) });
1503
1504
  for (const r of requires) console.error(formatInfo(`${r.name}: ${r.passed ? "passed" : r.pending ? "pending" : "unmet"}, ${r.reason}`));
@@ -1,11 +1,13 @@
1
1
  /**
2
2
  * `chant release` (#4026, ws-104): the release is what graduates.
3
3
  *
4
- * release cut [<label>] [--at <sha>] [--yes] [--build <command>] [--param k=v]... [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--json]
4
+ * release cut [<label>] [--at <sha>] [--yes] [--build <command>] [--param k=v]... [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--lane <name>] [--json]
5
5
  * a dry run of a cut of this member from the checkout's HEAD, which must be
6
- * clean, on trunk and pushed, and green (#4027); `--yes` cuts, records,
6
+ * clean, on trunk and pushed, and green (#4027), or green in a lane with
7
+ * `--lane` or `release.lane` (#4692); `--yes` cuts, records,
7
8
  * and tags the commit `release/<label>` locally;
8
- * --sign signs the cut with the actor's ssh key (#4031); `--src`, `-o` and
9
+ * --sign signs the cut with the actor's ssh key (#4031); `--override-green`
10
+ * cuts a commit that is not green under a person's override (#4693); `--src`, `-o` and
9
11
  * `--lexicon` shape the build of a project with no components (#4046)
10
12
  * release publish <label|digest> [--yes] [--allow-unsigned] [--require-provenance] [--json]
11
13
  * publish a cut release (#4027) to the targets release.publish declares
@@ -17,7 +19,7 @@
17
19
  * release verify <label|digest> [--json]
18
20
  * check the release's signature offline against .chant/allowed_signers
19
21
  * at the release's commit (#4049)
20
- * release candidates [--env <env>] [--json]
22
+ * release candidates [--env <env>] [--lane <name>] [--forge-issues] [--json]
21
23
  * the green commits of trunk a release can be cut from, each with what it
22
24
  * would ship, and what each environment runs (#4168 4.2)
23
25
  * release compose <name> [--base <label|sha>] (--pr <n> | --work <id>)... [--yes] [--json]
@@ -47,7 +49,7 @@ import { parseParamFlags } from "../build-params-cli";
47
49
  import type { CommandContext } from "../registry";
48
50
 
49
51
  const USAGE =
50
- "chant release cut [<label>] [--at <sha>] [--yes] [--build <command>] [--param <k=v>] [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--channel <tag>] [--json] | release publish <label|digest> [--yes] [--allow-unsigned] [--require-provenance] [--json] | release verify <label|digest> [--json] | release candidates [--env <env>] [--json] | release compose <name> [--base <label|sha>] (--pr <n> | --work <id>)... [--yes] [--json] | release list [--json] | release export <label|digest> --env <env> [-o <dir>] [--json]";
52
+ "chant release cut [<label>] [--at <sha>] [--yes] [--build <command>] [--param <k=v>] [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>] [--actor <name>] [--sign [<key file>]] [--channel <tag>] [--lane <name>] [--override-green] [--json] | release publish <label|digest> [--yes] [--allow-unsigned] [--require-provenance] [--json] | release verify <label|digest> [--json] | release candidates [--env <env>] [--lane <name>] [--forge-issues] [--json] | release compose <name> [--base <label|sha>] (--pr <n> | --work <id>)... [--yes] [--json] | release list [--json] | release export <label|digest> --env <env> [-o <dir>] [--json]";
51
53
 
52
54
  /** The build inputs `release cut` and `release compile` share. */
53
55
  function compileInputs(
@@ -94,6 +96,23 @@ export function sameWithYes(argv: readonly string[]): string {
94
96
  return ["chant", ...argv.filter((a) => a !== "--json" && a !== "--yes"), "--yes"].map(quote).join(" ");
95
97
  }
96
98
 
99
+ /**
100
+ * The green lane a cut or a candidates read checks (#4692): `--lane`, else
101
+ * `release.lane` in the member's chant.config.ts at `cwd`, else none. A
102
+ * config that can't be loaded is warned about and read as naming none, so the
103
+ * full green tag is checked.
104
+ */
105
+ async function laneOf(ctx: CommandContext, cwd: string): Promise<string | undefined> {
106
+ if (ctx.args.lane !== undefined) return ctx.args.lane;
107
+ try {
108
+ const { loadChantConfig } = await import("../../config");
109
+ return (await loadChantConfig(cwd)).config.release?.lane;
110
+ } catch (err) {
111
+ if (!ctx.args.json) console.error(formatWarning({ message: `release.lane was not read, so the full green tag is checked: ${err instanceof Error ? err.message : String(err)}` }));
112
+ return undefined;
113
+ }
114
+ }
115
+
97
116
  function describeActorSource(source: import("../../lifecycle/release-workstation").ActorSource): string {
98
117
  switch (source) {
99
118
  case "flag":
@@ -130,6 +149,14 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
130
149
  return 1;
131
150
  }
132
151
  const label = positional ?? args.label ?? null;
152
+ // #4693: the reason is the override's, written by the person who overrides.
153
+ if (args.reason !== undefined) {
154
+ console.error(formatError({
155
+ message: "release cut takes no --reason: an override's reason is on the override itself",
156
+ hint: "Cut with --override-green: it names the chant approve policy-override command that records the override and its reason.",
157
+ }));
158
+ return 1;
159
+ }
133
160
  const dryRun = args.yes !== true;
134
161
  const cwd = resolve(".");
135
162
  const { spawnTargetCompiler, ReleaseCompileError } = await import("../../components/release-compile");
@@ -226,6 +253,8 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
226
253
  if (args.at !== undefined && top && commit) checkout = at.checkoutCommit(top, cwd, commit);
227
254
  const cutCwd = checkout?.memberDir ?? cwd;
228
255
  const compiler = spawnTargetCompiler(compileInputs(ctx, params, cutCwd, label));
256
+ // #4692: the lane is the commit's own config's under --at.
257
+ const lane = await laneOf(ctx, cutCwd);
229
258
  const request = {
230
259
  cwd: cutCwd,
231
260
  compiler,
@@ -234,6 +263,8 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
234
263
  ...(args.sign !== undefined ? { sign: args.sign } : {}),
235
264
  ...(composed ? { composed } : {}),
236
265
  ...(args.channel ? { channel: args.channel } : {}),
266
+ ...(lane !== undefined ? { lane } : {}),
267
+ ...(args.overrideGreen ? { overrideGreen: true } : {}),
237
268
  };
238
269
 
239
270
  if (dryRun) {
@@ -274,13 +305,19 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
274
305
  return 0;
275
306
  }
276
307
  const name = plan.label ? formatBold(plan.label) : "an unlabelled release";
308
+ const greenIn = plan.override
309
+ ? `not green: no ${plan.override.tag.slice(0, plan.override.tag.lastIndexOf("/"))} tag`
310
+ : plan.lane !== null
311
+ ? `green in lane ${plan.lane}`
312
+ : "green";
277
313
  const where = composed
278
- ? ` (on ${trunk!.remote}/${composed.branch}, composed on ${composed.base.slice(0, 12)} from ${composed.sources.length} trunk commit(s), green)`
314
+ ? ` (on ${trunk!.remote}/${composed.branch}, composed on ${composed.base.slice(0, 12)} from ${composed.sources.length} trunk commit(s), ${greenIn})`
279
315
  : trunk
280
- ? ` (on ${trunk.remote}/${trunk.branch}, green)`
316
+ ? ` (on ${trunk.remote}/${trunk.branch}, ${greenIn})`
281
317
  : "";
282
318
  console.log(`Dry run: cut ${name} from commit ${plan.commit.slice(0, 12)}${where}`);
283
319
  if (args.channel) console.log(` channel ${args.channel}: a publish moves ${args.channel}, not latest`);
320
+ if (plan.override) console.log(` under the override by ${plan.override.by} at ${plan.override.at}${plan.override.sealed ? ", sealed" : ""}: ${plan.override.reason}; the cut spends it`);
284
321
  if (plan.alreadyCut) console.log(` already cut as ${plan.alreadyCut}: the cut would record nothing new`);
285
322
  console.log(` actor ${actor} (from ${describeActorSource(who.source)})`);
286
323
  console.log(` run ${ci ? `${ci.runId} (${ci.runOrigin.forge})` : "minted on this machine at the cut (local)"}`);
@@ -337,7 +374,7 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
337
374
  if (args.json) {
338
375
  console.log(
339
376
  JSON.stringify(
340
- { dryRun: false, release: result.release, label: result.label, cut: result.cut, stored: result.stored, reused: result.reused, actor, actorSource: who.source, tag: tagged, composed: composed ?? null, channel: args.channel ?? null, next },
377
+ { dryRun: false, release: result.release, label: result.label, cut: result.cut, stored: result.stored, reused: result.reused, actor, actorSource: who.source, tag: tagged, composed: composed ?? null, channel: args.channel ?? null, lane: lane ?? null, next },
341
378
  null,
342
379
  2,
343
380
  ),
@@ -346,8 +383,9 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
346
383
  const name = result.label ? formatBold(result.label) : "unlabelled release";
347
384
  if (result.cut) console.error(formatSuccess(`Cut ${name}: ${result.release.releaseDigest}`));
348
385
  else console.error(formatSuccess(`Already cut${result.label ? ` as ${formatBold(result.label)}` : ""}: ${result.release.releaseDigest}`));
349
- console.error(` commit ${result.release.commit}${composed ? `, composed on ${composed.base.slice(0, 12)} on ${composed.branch}` : ""}`);
386
+ console.error(` commit ${result.release.commit}${composed ? `, composed on ${composed.base.slice(0, 12)} on ${composed.branch}` : ""}${lane !== undefined ? `, green in lane ${lane}` : ""}`);
350
387
  if (args.channel) console.error(` channel ${args.channel}`);
388
+ if (result.cut?.override) console.error(` not green: cut under the override by ${result.cut.override.by}: ${result.cut.override.reason}`);
351
389
  if (result.cut) console.error(` ${result.cut.signature ? `signed by ${result.cut.actor}` : `not signed; actor ${result.cut.actor}`}, run ${result.cut.runId}`);
352
390
  console.error(` artifacts ${result.release.artifactDigests.length}, targets ${result.release.targets.map((t) => `${t.env} (${t.templates.length} template${t.templates.length === 1 ? "" : "s"})`).join(", ")}`);
353
391
  for (const r of result.reused) console.error(` ${r.component}: artifacts unchanged, carried from ${r.from}`);
@@ -361,6 +399,12 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
361
399
  return 0;
362
400
  } catch (err) {
363
401
  if (err instanceof ws.WorkstationCheckError || err instanceof ReleaseCutError || err instanceof at.CutAtError) {
402
+ // #4693: a request for an override goes where the person who answers it reads.
403
+ if (err instanceof ReleaseCutError && err.recorded) {
404
+ const { pushLifecycleReport } = await import("../../lifecycle/git");
405
+ const push = await pushLifecycleReport({ cwd }).catch(() => ({ pushed: false, pushWarning: undefined }));
406
+ if (push.pushWarning) console.error(formatWarning({ message: push.pushWarning }));
407
+ }
364
408
  return fail(err.code, err.message, err.fix);
365
409
  }
366
410
  if (err instanceof ReleaseLabelError) return fail(err.code, err.message);
@@ -495,8 +539,9 @@ export async function runReleasePublish(ctx: CommandContext): Promise<number> {
495
539
  const hint = promoteHint();
496
540
  if (hint) say(hint);
497
541
  } else {
498
- for (const p of published) for (const i of p.items) say(` ${i.present ? "already there" : "published"}: ${describeItem(i)}`);
499
- console.error(formatSuccess(`Published ${name} to ${published.length} target(s)`));
542
+ for (const p of published) for (const i of p.items) say(` ${i.refused ? "refused" : i.present ? "already there" : "published"}: ${describeItem(i)}`);
543
+ const refused = published.filter((p) => p.warning);
544
+ console.error(formatSuccess(`Published ${name} to ${published.length - refused.length} target(s)${refused.length > 0 ? `; ${refused.length} refused it, with a warning` : ""}`));
500
545
  }
501
546
  return 0;
502
547
  }
@@ -550,14 +595,23 @@ export async function runReleaseVerify(ctx: CommandContext): Promise<number> {
550
595
  }
551
596
 
552
597
  /**
553
- * `release candidates [--env <env>] [--json]` (#4168 4.2): the green commits
554
- * of trunk a release can be cut from, newest first, each with what it would
555
- * ship since the previous one, and what each environment runs. `--json`
598
+ * `release candidates [--env <env>] [--forge-issues] [--json]` (#4168 4.2):
599
+ * the green commits of trunk a release can be cut from, newest first, each
600
+ * with what it would ship since the previous one, and what each environment
601
+ * runs. `--forge-issues` (#4649) asks the forge which issues each pull
602
+ * request closes and groups the changes no work id names by them. `--json`
556
603
  * prints the read contract's `release-candidates` document.
557
604
  */
558
605
  export async function runReleaseCandidates(ctx: CommandContext): Promise<number> {
559
606
  const { releaseCandidatesDocument } = await import("../../workspace/release-candidates");
560
- const doc = await releaseCandidatesDocument({ cwd: resolve("."), ...(ctx.args.env ? { env: ctx.args.env } : {}), ...(ctx.args.branch ? { branch: ctx.args.branch } : {}) });
607
+ const lane = await laneOf(ctx, resolve("."));
608
+ const doc = await releaseCandidatesDocument({
609
+ cwd: resolve("."),
610
+ ...(ctx.args.env ? { env: ctx.args.env } : {}),
611
+ ...(ctx.args.branch ? { branch: ctx.args.branch } : {}),
612
+ ...(lane !== undefined ? { lane } : {}),
613
+ ...(ctx.args.forgeIssues ? { forgeIssues: {} } : {}),
614
+ });
561
615
  if (ctx.args.json) {
562
616
  console.log(JSON.stringify(doc, null, 2));
563
617
  return "error" in doc ? 1 : 0;
@@ -574,15 +628,17 @@ export async function runReleaseCandidates(ctx: CommandContext): Promise<number>
574
628
  console.error(`No candidates: this clone knows no ${doc.branch}. Fetch it: git fetch origin ${doc.branch} --tags`);
575
629
  return 0;
576
630
  }
577
- if (doc.pending.length > 0) console.log(`${doc.pending.length} commit(s) on ${doc.branch} after the newest candidate are not green yet`);
578
- if (doc.candidates.length === 0) console.log(`No green commit on ${doc.branch}${doc.since ? ` since ${doc.since.slice(0, 12)}` : ""} to cut from.`);
631
+ const greenIn = doc.lane !== null ? `green in lane ${doc.lane}` : "green";
632
+ if (doc.lane !== null) console.log(`Lane ${doc.lane}: candidates carry ci/green-${doc.lane}/<sha>`);
633
+ if (doc.pending.length > 0) console.log(`${doc.pending.length} commit(s) on ${doc.branch} after the newest candidate are not ${greenIn} yet`);
634
+ if (doc.candidates.length === 0) console.log(`No ${greenIn} commit on ${doc.branch}${doc.since ? ` since ${doc.since.slice(0, 12)}` : ""} to cut from.`);
579
635
  for (const c of doc.candidates) {
580
636
  const tags = [...(c.newFor.length > 0 ? [`new for ${c.newFor.join(", ")}`] : []), ...(c.cut.length > 0 ? [`cut as ${c.cut.join(", ")}`] : [])];
581
637
  console.log(`${c.commit.slice(0, 12)} ${c.subject}${tags.length > 0 ? ` (${tags.join("; ")})` : ""}`);
582
638
  // #4168 4.4: by work item, then pull request, then commit.
583
639
  const subjectOf = new Map(c.changes.map((ch) => [ch.commit, ch.subject]));
584
640
  for (const g of c.groups) {
585
- console.log(` ${g.work !== null ? `work:${g.work}` : "no work item"}`);
641
+ console.log(` ${g.work !== null ? `work:${g.work}` : g.issue !== null ? `issue #${g.issue}` : "no work item"}`);
586
642
  for (const p of g.pullRequests) {
587
643
  console.log(` ${p.pr !== null ? `#${p.pr}` : "no pull request"}`);
588
644
  for (const sha of p.commits) console.log(` ${sha.slice(0, 12)} ${subjectOf.get(sha) ?? ""}`);
@@ -591,7 +647,10 @@ export async function runReleaseCandidates(ctx: CommandContext): Promise<number>
591
647
  for (const f of c.flags) console.log(` flag ${f.id} (${f.member} ${f.param}) changed`);
592
648
  }
593
649
  for (const sk of doc.skipped) console.log(`skipped ${sk.commit.slice(0, 12)} ${sk.subject} (revoked)`);
594
- if (doc.candidates.length > 0) console.error(`Cut one: chant release cut <label> --at <sha>`);
650
+ // --forge-issues: why a pull request's issues were not read, once per reason.
651
+ const unread = new Set([...doc.candidates.flatMap((c) => c.changes), ...doc.pending].map((ch) => ch.closes?.reason).filter((r): r is string => typeof r === "string"));
652
+ for (const r of unread) console.error(`Issues not read from the forge: ${r}`);
653
+ if (doc.candidates.length > 0) console.error(`Cut one: chant release cut <label> --at <sha>${doc.lane !== null && ctx.args.lane !== undefined ? ` --lane ${doc.lane}` : ""}`);
595
654
  return 0;
596
655
  }
597
656
 
@@ -617,8 +676,13 @@ export async function runReleaseList(ctx: CommandContext): Promise<number> {
617
676
  const newest = r.cuts.at(-1);
618
677
  const signature = newest ? (newest.signatureCheck.status === "verified" ? `signed by ${newest.actor}` : newest.signatureCheck.status) : "-";
619
678
  // #4033: a release cut from a revoked commit says so at the end of its line, and why on stderr.
620
- console.log(`${(r.label ?? "-").padEnd(16)} ${r.releaseDigest} ${r.commit.slice(0, 12)} ${signature} ${where}${r.revoked ? " revoked" : ""}`);
679
+ // #4692: a release cut from a lane's green tag names the lane.
680
+ const lane = r.cuts.find((c) => c.lane !== undefined)?.lane;
681
+ const overridden = r.cuts.some((c) => c.override !== undefined);
682
+ console.log(`${(r.label ?? "-").padEnd(16)} ${r.releaseDigest} ${r.commit.slice(0, 12)} ${signature} ${where}${lane !== undefined ? ` lane ${lane}` : ""}${overridden ? " not green" : ""}${r.revoked ? " revoked" : ""}`);
621
683
  if (newest?.signatureCheck.status === "unverified") console.error(` ${r.label ?? r.releaseDigest}: ${newest.signatureCheck.reason}`);
684
+ // #4693: a release cut under an override says the commit was not green.
685
+ for (const c of r.cuts) if (c.override) console.error(` ${r.label ?? r.releaseDigest}: not green (no ${c.override.tag}), cut under the override by ${c.override.by}: ${c.override.reason}`);
622
686
  if (r.revoked) {
623
687
  const { describeRevocation } = await import("../../lifecycle/release-revocation");
624
688
  console.error(` ${r.label ?? r.releaseDigest}: revoked by ${r.revoked.tag}, ${describeRevocation(r.revoked)}`);