@kontourai/flow-agents 3.2.0 → 3.4.0

package/build/src/cli/workflow-sidecar.d.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { type EffectiveState } from "./assignment-provider.js";
 type AnyObj = Record<string, any>;
 export declare const statuses: Set<string>;
 export declare const phases: string[];
@@ -132,6 +133,36 @@ type SurfaceModule = {
         assuranceLevel: "signed";
     } | null>;
 };
+/**
+ * Fold a raw command-log (command-log.jsonl entries) into a per-command classification,
+ * keyed by normalized command text (whitespace-collapsed, trimmed). Pure and side-effect-free
+ * so it is directly unit-testable (#470 iteration 2, finding #2 — HIGH: the prior inline reducer
+ * collapsed every non-"fail" `observedResult` — including "ambiguous" — to "pass", feeding a
+ * verified event + `passing:true` and reintroducing the #470 false-pass through the trust-bundle
+ * reconciliation path).
+ *
+ * Three-way classification, keyed on `observedResult` (never re-derived from `exitCode` alone,
+ * which would miscoerce the #362 grep/diff absence carve-out `ambiguous,exitCode:1` entry to
+ * `fail`):
+ *   - "fail"      when `observedResult==="fail"`, or (legacy, no observedResult) a nonzero
+ *                 integer `exitCode`.
+ *   - "ambiguous" when `observedResult==="ambiguous"`, or (legacy) `exitCode` is `null` with no
+ *                 fail signal.
+ *   - "pass"      when `observedResult==="pass"`, or (legacy) `exitCode===0`.
+ *
+ * Precedence across repeated entries for the same command: fail > pass > ambiguous. A genuine
+ * exit-0 pass is positive evidence and confirms; ambiguous holds only when there is neither a
+ * fail nor a positive pass, since a "pass" always requires positive evidence.
+ *
+ * The caller (buildTrustBundle) maps "ambiguous" onto the existing canonical non-confirming
+ * status `not_verified` — consume-never-fork, mirroring record-check's identical mapping — so
+ * `checkStatusToEventStatus("not_verified")` returns null (no verification event emitted) and the
+ * evidence item is stamped `passing:false`. See Decision/finding #2 in the iteration-2 plan.
+ */
+export declare function reduceCaptureLogByCommand(commandLog: AnyObj[] | undefined): Map<string, {
+    observedResult: "pass" | "fail" | "ambiguous";
+    exitCode: number | null;
+}>;
 /**
  * Build a Hachure trust.bundle from raw check/criterion/critique inputs.
  * trust.bundle is the PRIMARY artifact (ADR 0010 Phase 4a producer inversion).
@@ -166,7 +197,7 @@ export declare function writeTrustBundle(dir: string, slug: string, timestamp: s
 export declare function sidecarBase(slug: string): AnyObj;
 export declare function validateEvidenceRef(ref: AnyObj, label: string): AnyObj;
 export declare function normalizeEvidenceRefs(raw: unknown, label: string): AnyObj[];
-export declare function normalizeCheck(raw: AnyObj): AnyObj;
+export declare function normalizeCheck(raw: AnyObj, allowGateClaimPrefix?: boolean, existingCheckStampById?: ReadonlyMap<string, boolean>): AnyObj;
 /**
  * Derive kit identity from a parsed trust.bundle by structurally reading the
  * DECLARED primary claim (kit-typed) rather than hardcoding "builder".
@@ -201,6 +232,235 @@ export declare function normalizeFinding(raw: AnyObj): AnyObj;
  * Signing is ALWAYS fail-open — a signing failure never breaks the seal.
  */
 export declare function sealTrustCheckpoint(dir: string, slug: string, sealedAt: string, status: string, phase: string): Promise<void>;
+/**
+ * Distinct, identifiable error for a shape-invalid trust.bundle — NOT a generic Error, so
+ * every publishDelivery() call site (advanceState/recordRelease/promote/publishDeliveryCmd)
+ * can positively distinguish "refuses to publish an invalid bundle" (must be LOUD, fail
+ * closed, AC6) from the other failure modes those call sites already tolerate as best-effort
+ * (missing kits/ ancestor for a scratch dir, I/O errors, etc — see each catch's own comment).
+ * A bare `instanceof Error` check would not suffice since every thrown failure in this file is
+ * already an Error; `code` is the recognizable, grep-stable discriminator.
+ */
+export declare class InvalidBundleShapeError extends Error {
+    readonly code: "RECONCILE_PREFLIGHT_INVALID_SHAPE";
+    readonly issues: string[];
+    constructor(issues: string[]);
+}
+/**
+ * Distinct, identifiable error for a publish attempt by an actor who is NOT the fresh,
+ * non-superseded holder of the subject (issue #293, ADR 0021 §3) — NOT a generic Error and NOT
+ * `InvalidBundleShapeError` (#356), so every publishDelivery() call site can positively
+ * distinguish "refuses to publish because the bundle shape is invalid" from "refuses to publish
+ * because this actor no longer holds the subject" — two genuinely distinct fail-closed tiers
+ * that must never be conflated in a catch handler (a worker fixing a shape issue must not be
+ * told to "re-record evidence" when the real problem is a stale/superseded claim, and vice
+ * versa). Mirrors `InvalidBundleShapeError`'s shape exactly: same `extends Error` base, same
+ * `readonly code` discriminator convention, same doc-comment structure — only the payload
+ * differs (the effective-state/holder/reason/guidance `runVerifyHold()` computed, rather than a
+ * shape-issue list).
+ */
+export declare class NotFreshHolderError extends Error {
+    readonly code: "VERIFY_HOLD_NOT_FRESH_HOLDER";
+    readonly effective_state: EffectiveState | "not_evaluated";
+    readonly holder?: {
+        actor?: string;
+        assignee?: string | null;
+        idle_days?: number | null;
+        last_at?: string;
+    };
+    readonly reason: string;
+    readonly guidance: string[];
+    constructor(result: {
+        effective_state: EffectiveState | "not_evaluated";
+        holder?: {
+            actor?: string;
+            assignee?: string | null;
+            idle_days?: number | null;
+            last_at?: string;
+        };
+        reason: string;
+        guidance: string[];
+    });
+}
+/**
+ * Distinct, identifiable error for a publish attempt whose resolved `repoRoot` does not
+ * positively confirm the session's sealed `trust.checkpoint.json` `commit_sha` — a FOURTH,
+ * distinct fail-closed tier (#413 Facet A), never conflated with `InvalidBundleShapeError`
+ * (bundle shape) or `NotFreshHolderError` (actor hold). This is the "refuse loudly when the cwd
+ * repo does not match the sealed checkpoint commit_sha" fallback the issue itself proposed:
+ * `publishDelivery`'s `repoRoot` is resolved by walking up from the ARTIFACT directory
+ * (findRepoRootFromDirStrict), which always physically lives under the primary checkout even
+ * when invoked from an unrelated worktree/repo — so a positively-confirmed mismatch here is the
+ * signal that this resolved repoRoot is NOT the repo the sealed checkpoint was produced against,
+ * and publishing into it would silently write to the wrong tree.
+ *
+ * #413 iteration-2 Fix 4: thrown for the ONE positively-determinable `mismatchKind` (see
+ * checkpointHeadAncestry's doc comment) — `"positive"` (repoRoot's HEAD is confirmed NOT an
+ * ancestor-or-equal of commit_sha; `headSha` is a real sha). It is intentionally NEVER thrown for
+ * `"undeterminable-shallow"` (e.g. a shallow clone missing the commit object) — that case only
+ * warns and allows the publish (see publishDelivery's own gate). A non-git `repoRoot` classifies
+ * as `mismatchKind === "none"` (no opinion — allow; see checkpointHeadAncestry's doc comment for
+ * why the iteration-2 Fix 5 refusal here was reverted in iteration-3) and never throws this error
+ * either.
+ */
+export declare class RepoHeadMismatchError extends Error {
+    readonly code: "PUBLISH_DELIVERY_REPO_HEAD_MISMATCH";
+    readonly repoRoot: string;
+    readonly commitSha: string;
+    readonly headSha: string;
+    constructor(repoRoot: string, commitSha: string, headSha: string);
+}
+export declare function runReconcilePreflight(dir: string, repoRoot: string, manifestOverride?: string | null): {
+    ok: boolean;
+    issues: string[];
+    warnings: string[];
+};
+/**
+ * The ONE hard-stop gate (issue #293, ADR 0021 §3): "is my actor the fresh, non-superseded
+ * holder of this subject (or is the subject free/self-held)?" Reuses the SAME assignment ⋈
+ * liveness join #290/#291 already built (`computeEffectiveState` + `readLocalAssignmentStatus`
+ * + `readLivenessEvents`/`freshHolders`) — no second computation is invented here. This is the
+ * mirror-image check, at the OTHER end of the session lifecycle, of
+ * `enforceEnsureSessionOwnership`'s pre-entry guard above: that guard decides whether entry
+ * should claim/supersede/refuse; this gate decides whether PUBLISH should proceed, with a
+ * different (new) per-effective-state mapping — the ownership guard's "claim"/"supersede"
+ * actions are wrong at publish time, so this is new interpretation of the existing join output,
+ * not a new join and not a new `EffectiveState` value (there is no literal `"superseded"` state
+ * — a superseded-away actor's own re-check naturally resolves to `held`(holder=successor) or
+ * `reclaimable`, never `self_is_holder`; see assignment-provider.ts's `computeEffectiveState`).
+ *
+ * Effective-state -> publish-decision mapping (the operative spec, from the plan's table).
+ * IMPORTANT (bug fix, #397): this gate fences the durable ASSIGNMENT hold, not ambient
+ * liveness — liveness is advisory everywhere else in the system, and this is the ONE hard
+ * gate, so it must never false-block on liveness alone. A subject with fresh liveness by
+ * another actor but NO durable assignment record (`held`, reason
+ * `liveness_claim_present_assignment_lagging`) therefore PASSES, not BLOCKs — there is no
+ * durable ownership conflict to protect, only ambient presence. This does NOT weaken zombie
+ * protection: a superseded zombie always has an assignment record (either its own stale
+ * assignment — `reclaimable` — or the successor's assignment-backed `held`/
+ * `fresh_liveness_heartbeat`), both of which still BLOCK below.
+ *   - `free` (no assignment ever recorded)              -> PASS (never false-block an untracked subject)
+ *   - `held`, reason `self_is_holder`                    -> PASS (the caller IS the current holder)
+ *   - `held`, reason `liveness_claim_present_assignment_lagging`
+ *     (fresh liveness by another actor, NO durable assignment record) -> PASS (liveness alone
+ *     is never a durable ownership conflict — see #397 fix note above)
+ *   - `held`, reason `fresh_liveness_heartbeat`
+ *     (durable assignment held by another actor + fresh liveness)     -> BLOCK (a different
+ *     actor durably holds this subject and is demonstrably still live)
+ *   - `reclaimable` (assignment present, stale/absent liveness)       -> BLOCK (not proof of
+ *     self — safe default blocks; a durable assignment record exists)
+ *   - `human-held`                                        -> BLOCK (never publish over a human assignee)
+ *   - no resolvable join at all (non-local-file provider
+ *     with no --effective-state-json)                    -> `not_evaluated`, PASS (documented scope
+ *                                                             boundary, loud stderr note, never a silent block)
+ *
+ * Actor resolution mirrors `enforceEnsureSessionOwnership` EXACTLY: the bare
+ * `resolveActor(env).actor` / branchActorKey string, NEVER `serializeActor(actorStruct)`'s
+ * triple — the #291 flat-vs-triple seam. `opts.actorKey` (the CLI's --actor / FLOW_AGENTS_ACTOR
+ * override, already sanitized by the caller) takes precedence when provided.
+ *
+ * Slug/artifactRoot derivation matches `publishDelivery()`'s own `slug =
+ * path.basename(path.resolve(dir))` byte-for-byte (both must resolve the SAME assignment
+ * record) and the `artifactRoot = path.dirname(dir)` pattern already used elsewhere in this
+ * file for a `dir`-only consumer.
+ *
+ * github provider: read-only precomputed `--effective-state-json` escape hatch, matching
+ * `enforceEnsureSessionOwnership`'s existing github branch precedent exactly (render-don't-
+ * execute — assignment-provider.ts never calls `gh` directly from this CLI).
+ *
+ * Every interpolated actor/holder/reason string is sanitized via
+ * `stripControlCharsForDisplay(...).slice(0, 64)` — reusing the exact top-level helper, never a
+ * second sanitizer (AC7).
+ *
+ * SECOND CI-blocking false-block fix (this iteration): the hard gate above enforces ONLY for a
+ * STABLY-identified actor. A caller's identity is STABLE when it comes from an explicit
+ * `opts.actorKey` (a caller that hands in an actor key is asserting a stable identity — e.g. the
+ * CLI's --actor / FLOW_AGENTS_ACTOR override, or the github skill's precomputed path), from
+ * `FLOW_AGENTS_ACTOR` (`resolveActor` source `"explicit-override"`), or from a runtime-native
+ * session id (`resolveActor` source `` `runtime-session-id:${runtime}` ``, e.g. Claude Code's
+ * `CLAUDE_CODE_SESSION_ID`). It is UNSTABLE when `resolveActor` falls all the way through to the
+ * process-ancestry fallback (source `"process-ancestry"`) or fails to resolve at all (source
+ * `"unresolved"` / `isUnresolvedActor(actor)`). This mirrors `enforceEnsureSessionOwnership`'s
+ * Design Decision 4 (never hard-fail on actor ambiguity): a session that cannot stably
+ * self-identify cannot be meaningfully fenced against a durable assignment record, so hard-
+ * blocking it produces exactly the false-block CI hit (no `FLOW_AGENTS_ACTOR`/runtime session id
+ * in CI -> ancestry fallback -> a DIFFERENT ancestry-derived actor string than the one that
+ * created the claim -> `reclaimable`/not-self -> hard BLOCK of a legitimate self-publish). A
+ * real coordination participant always has a stable identity (explicit override or runtime
+ * session id), so zombie protection under a stable actor is completely unaffected — this only
+ * changes behavior for a caller that was never fenceable in the first place. When the resolved
+ * actor identity is UNSTABLE, this function short-circuits to `{ ok: true, effective_state:
+ * "not_evaluated", reason: "actor-identity-unstable-advisory-only" }` (holder included, sanitized,
+ * when one exists) BEFORE running the assignment ⋈ liveness join at all, with one loud stderr
+ * note — the gate degrades to advisory-only rather than ever false-blocking an unstable identity.
+ * When the actor identity IS stable, the effective-state -> publish-decision mapping above
+ * applies exactly as documented, unchanged.
+ */
+export declare function runVerifyHold(dir: string, repoRoot: string | null, opts?: {
+    actorKey?: string;
+    now?: number;
+    assignmentProviderKind?: string;
+    effectiveStateJson?: unknown;
+}): {
+    ok: boolean;
+    effective_state: EffectiveState | "not_evaluated";
+    holder?: {
+        actor?: string;
+        assignee?: string | null;
+        idle_days?: number | null;
+        last_at?: string;
+    };
+    reason: string;
+    guidance: string[];
+};
+/**
+ * Render (never execute) the takeover protocol for a candidate the skill has selected. Takeover is
+ * RESUMPTION, not restart: when a subject is `reclaimable` (a durable assignment whose incumbent is
+ * no longer heartbeating), a successor must (1) grace-beat — wait one heartbeat interval and re-check,
+ * backing off if the incumbent revives — (2) supersede via `ensure-session --supersede-stale`, and
+ * (3) CONTINUE THE INCUMBENT'S BRANCH (from the incumbent's claim record), never a parallel one, and
+ * re-enter the SAME artifact dir (deterministic slug). This function computes the effective state
+ * (the same assignment ⋈ liveness join verify-hold/ensure-session use) and emits the appropriate
+ * action + the incumbent's `resume_branch`; the skill executes the beat/supersede/git steps.
+ *
+ * Race-safety is CLI-enforced at supersede time, not here: `ensure-session --supersede-stale`
+ * re-computes the state and refuses (dies on `held`) if the incumbent revived during the beat, so a
+ * successor that skipped or lost the grace race still cannot supersede a live incumbent (AC2a).
+ *
+ * ADVISORY, not a gate: the assignment ⋈ liveness JOIN is identical to verify-hold's, but this render
+ * only advises the skill which action to take — the ACTUAL enforcement is `ensure-session
+ * --supersede-stale` (re-check under a subject lock). So it deliberately does NOT replicate
+ * verify-hold's #398 `isStableActor` tiering (which exists there only because verify-hold is a hard
+ * publish BLOCK that must not false-block an unstable/ancestry identity): a wrong self-identification
+ * here yields only a wrong advisory string, never a wrong mutation.
+ *
+ * Ordering note: ADR 0021 §5's literal wording is supersede→grace→maybe-undo; this implements
+ * grace→recheck→supersede (never write until the beat confirms the incumbent stayed stale) — a
+ * deliberate, safer variant that preserves the ADR's intent ("laptop just woke resolves in the
+ * incumbent's favor") without a premature write to walk back.
+ *
+ * All untrusted fields (incumbent actor / branch / last_at, sourced from the shared multi-writer
+ * assignment+liveness stream) pass through `sanitize`/`sanitizeWide` (stripControlCharsForDisplay +
+ * the repo's 64/240 cap tiers — branch uses the 240 free-text tier so a valid long branch is never
+ * truncated into a bad checkout target) — the #287/#320/#293 injection class.
+ */
+export declare function runTakeoverPreflight(dir: string, opts?: {
+    actorKey?: string;
+    now?: number;
+    graceSeconds?: number;
+}): {
+    ok: boolean;
+    action: "grace-then-supersede" | "back-off" | "claim" | "ask-first" | "proceed";
+    effective_state: EffectiveState;
+    reason: string;
+    holder?: {
+        actor?: string;
+        last_at?: string;
+    };
+    resume_branch?: string;
+    grace_seconds?: number;
+    next_steps: string[];
+};
 /**
  * Publish the session's trust artifacts to the committed delivery/ path.
  *
@@ -226,6 +486,55 @@ export declare function sealTrustCheckpoint(dir: string, slug: string, sealedAt:
  * evals/integration/test_checkpoint_signing.sh TEST 2 and the WS5 session findings at
  * .kontourai/flow-agents/ws5-governance-kit-slice1 for the root cause this fixes).
  * Idempotent: overwrites on re-delivery to the same slug.
+ *
+ * #356 Wave 3 (AC6): Fail-CLOSED on bundle SHAPE. After the fail-soft absence guard below,
+ * runs the SAME reconcile-preflight shape check (runReconcilePreflight) the
+ * `reconcile-preflight` CLI subcommand exposes, BEFORE copying anything into delivery/. A
+ * shape-invalid bundle throws InvalidBundleShapeError (a distinct, identifiable error — see
+ * its own doc comment) rather than silently publishing a bundle CI's Trust Reconcile job
+ * would reject anyway. This is intentionally a NEW, additive fail-closed branch — it must
+ * never be conflated with the pre-existing fail-soft absence/repo-root branches above/below,
+ * which stay exactly as before (see each publishDelivery call site's catch handler for how
+ * the distinction is preserved end-to-end).
+ *
+ * #293 (THIRD, DISTINCT fail-closed gate): immediately after the shape check above and BEFORE
+ * writing anything into delivery/, runs `runVerifyHold()` — the assignment ⋈ liveness join
+ * asking "is the calling actor the fresh, non-superseded holder of this subject (or is it
+ * free/self-held)?" A not-fresh-holder result throws `NotFreshHolderError` (distinct from
+ * `InvalidBundleShapeError` — a different `code`, a different failure mode: actor hold vs
+ * bundle shape).
+ *
+ * #413 Facet A (FOURTH, DISTINCT fail-closed gate): immediately after the verify-hold gate and
+ * BEFORE writing anything into delivery/, compares the resolved `repoRoot`'s `git rev-parse
+ * HEAD` against the session's sealed `trust.checkpoint.json` `commit_sha` (via the shared
+ * checkpointHeadAncestry() helper — the SAME ancestor-check checkpointStalenessWarning already
+ * used as a non-blocking warning). Throws `RepoHeadMismatchError` (distinct from both other
+ * error tiers) instead of silently publishing into what is very likely the WRONG repo (e.g.
+ * `repoRoot` resolved to the primary checkout via findRepoRootFromDirStrict's artifact-dir
+ * walk, even though this session's checkpoint was sealed against a DIFFERENT worktree's HEAD).
+ * A session with no checkpoint yet, or a checkpoint with no commit_sha, has nothing to compare
+ * against and is unaffected (scoped strictly to the mismatch case, never a spurious refusal).
+ *
+ * #413 iteration-2 Fix 4 (see checkpointHeadAncestry's own doc comment for the full
+ * `mismatchKind` classification this gate reads): only `mismatchKind === "positive"` (a
+ * POSITIVELY-DETERMINABLE ancestry mismatch — the real wrong-tree harm case) hard refuses here.
+ * `"undeterminable-shallow"` (e.g. a local shallow clone missing the commit_sha object) must
+ * NEVER hard-refuse a legitimate publish — this branch only WARNS loudly and lets the shape +
+ * verify-hold gates above continue to stand guard. A non-git `repoRoot` classifies as
+ * `mismatchKind === "none"` (allow) — iteration-2's Fix 5 hard-refused this case too, but that
+ * regressed the SUPPORTED non-git-repoRoot scratch/checkpoint-signing flow (see
+ * evals/integration/test_checkpoint_signing.sh TEST 2) and was reverted in iteration-3. Wrong-tree
+ * protection for that case relies on the shape-check and verify-hold gates above, which correctly
+ * no-op (allow) when there is no git repo to inspect, same as this gate.
+ *
+ * There are now FOUR fail-closed/fail-soft TIERS in this function, and they must never be
+ * conflated in prose or in a call site's catch handler: (1) fail-SOFT bundle absence /
+ * repo-root resolution (silent no-op / visible warning, unchanged from before #356), (2)
+ * fail-CLOSED bundle shape (#356, `InvalidBundleShapeError`), (3) fail-CLOSED verify-hold (#293,
+ * `NotFreshHolderError`), (4) fail-CLOSED repo-HEAD-vs-checkpoint mismatch (#413 Facet A,
+ * `RepoHeadMismatchError`) — see this tier's own gate below for the undeterminable-shallow
+ * carve-out. Tiers run in this fixed order (shape, then verify-hold, then HEAD-mismatch); a
+ * bundle that fails an earlier tier throws that tier's error specifically, never a later one's.
  */
 export declare function publishDelivery(dir: string, repoRoot: string | null): Promise<void>;
 export declare function validateLearningCorrection(record: AnyObj): void;