@kontourai/flow-agents 3.2.0 → 3.3.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[];
@@ -201,6 +202,207 @@ 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[];
+    });
+}
+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 +428,28 @@ 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 (SECOND, 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). There are now THREE tiers here, 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`). The
+ * shape check runs first (per the plan's ordering) — a bundle that is BOTH shape-invalid and
+ * not-held throws `InvalidBundleShapeError` specifically, never `NotFreshHolderError`.
  */
 export declare function publishDelivery(dir: string, repoRoot: string | null): Promise<void>;
 export declare function validateLearningCorrection(record: AnyObj): void;