@kontourai/flow-agents 2.4.0 → 3.1.0

package/build/src/cli/assignment-provider.js

@@ -0,0 +1,805 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { parseArgs, flagString } from "../lib/args.js";
+import { readJson, writeJson, isoNow } from "../lib/fs.js";
+const DEFAULT_LABEL_NAME = "agent:claimed";
+const CLAIM_COMMENT_MARKER_DEFAULT = "<!-- flow-agents:assignment-claim -->";
+/**
+ * Delegate to the shared pure-CJS resolver (scripts/hooks/lib/actor-identity.js), mirroring the
+ * exact createRequire pattern `workflow-sidecar.ts`'s loadActorIdentityHelper() already uses for
+ * this module. Deliberately NO inline duplicate fallback — same rationale as that function: if
+ * the module fails to load, that failure must surface loudly, never silently degrade to a forked
+ * actor concept or a second sanitizer.
+ */
+function loadActorIdentityHelper() {
+    const _req = createRequire(import.meta.url);
+    const helperPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../scripts/hooks/lib/actor-identity.js");
+    return _req(helperPath);
+}
+/**
+ * Delegate to the shared pure-CJS liveness reader (scripts/hooks/lib/liveness-read.js), same
+ * createRequire idiom as loadActorIdentityHelper() above. Used only for the join computation —
+ * this module never writes liveness events (that stays the ADR 0012 lifecycle's job).
+ */
+function loadLivenessReadHelper() {
+    const _req = createRequire(import.meta.url);
+    const helperPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../scripts/hooks/lib/liveness-read.js");
+    return _req(helperPath);
+}
+function loadJsonInput(file) {
+    return file === "-" ? JSON.parse(fs.readFileSync(0, "utf8")) : readJson(file);
+}
+function requireFlag(args, name) {
+    const value = flagString(args.flags, name);
+    if (!value)
+        throw new Error(`--${name} is required`);
+    return value;
+}
+/**
+ * Build an ActorStruct from an already-loaded JSON value (used for --actor-json,
+ * --from-actor-json, --to-actor-json). Fails loud on a malformed/incomplete struct — a
+ * durable claim record must never carry a partial actor identity.
+ */
+function actorStructFromJson(data, sourceLabel) {
+    if (typeof data !== "object" || data === null)
+        throw new Error(`${sourceLabel} must contain an object`);
+    const struct = data;
+    if (!struct.runtime || !struct.session_id || !struct.host)
+        throw new Error(`${sourceLabel} must include runtime, session_id, and host`);
+    return {
+        runtime: String(struct.runtime),
+        session_id: String(struct.session_id),
+        host: String(struct.host),
+        human: struct.human != null && String(struct.human).trim() !== "" ? String(struct.human) : null,
+    };
+}
+function loadActorStructFromFile(file) {
+    return actorStructFromJson(loadJsonInput(file), `actor JSON (${file})`);
+}
+/**
+ * Resolve the acting actor for a local-file mutation: --actor-json is the deterministic,
+ * fixture-friendly path (used by evals and any caller that already knows its own struct);
+ * when omitted, auto-derive from the live environment via the shared resolver, mirroring
+ * (never forking) the exact struct fields serializeActor() already defines.
+ *
+ * F1 fix (fix-plan iteration 1, HIGH): also returns `actorKey` — set to the canonical
+ * `resolveActor(env).actor` string ONLY on the auto-derive path (pull-work's real path, and any
+ * other caller with no --actor-json), so a claim made via `assignment-provider claim` and one
+ * made via ensure-session share the same canonical key. `--actor-json` explicit fixtures leave
+ * `actorKey` unset — `performLocalClaim`/`performLocalSupersede` then fall back to
+ * `serializeActor(actor)` for the record's `actor_key`, preserving existing fixture behavior.
+ */
+function loadActorStruct(args) {
+    const actorJsonPath = flagString(args.flags, "actor-json");
+    if (actorJsonPath)
+        return { actor: loadActorStructFromFile(actorJsonPath) };
+    const helper = loadActorIdentityHelper();
+    const resolved = helper.resolveActor(process.env);
+    if (helper.isUnresolvedActor(resolved.actor))
+        throw new Error("could not resolve an actor identity (no --actor-json and no resolvable environment actor); pass --actor-json explicitly");
+    return { actor: { runtime: helper.detectRuntime(process.env), session_id: resolved.actor, host: os.hostname(), human: null }, actorKey: resolved.actor };
+}
+export function assignmentFilePath(artifactRoot, subjectId) {
+    const sanitized = loadActorIdentityHelper().sanitizeSegment(subjectId);
+    return path.join(artifactRoot, "assignment", `${sanitized}.json`);
+}
+export function readLocalRecord(artifactRoot, subjectId) {
+    const file = assignmentFilePath(artifactRoot, subjectId);
+    if (!fs.existsSync(file))
+        return null;
+    let data;
+    try {
+        data = readJson(file);
+    }
+    catch (error) {
+        // Fail loud: a corrupt claim record must never be silently treated as "no claim" — that
+        // would be a fail-open path that could let a second claim silently overwrite a real one.
+        throw new Error(`assignment record is corrupt, refusing to proceed: ${file}: ${error.message}`);
+    }
+    if (typeof data !== "object" || data === null)
+        throw new Error(`assignment record is not an object: ${file}`);
+    const record = data;
+    if (record.schema_version !== "1.0")
+        throw new Error(`${file}: unsupported schema_version ${String(record.schema_version)}`);
+    return record;
+}
+export function writeLocalRecord(artifactRoot, subjectId, record) {
+    // writeJson throws on any mkdir/writeFileSync failure; that error is intentionally allowed to
+    // propagate to main()'s top-level try/catch and exit non-zero. Durable writes must fail loud,
+    // never fail open (artifact-contract.md).
+    writeJson(assignmentFilePath(artifactRoot, subjectId), record);
+}
+/**
+ * Synchronous busy-sleep via Atomics.wait on a throwaway SharedArrayBuffer — Node.js (unlike
+ * browser engines) permits Atomics.wait on the main thread, so this gives withSubjectLock() a
+ * true blocking sleep without going async. Kept to a small, bounded delay (see withSubjectLock's
+ * spin loop) — never used outside the lock-acquire spin below.
+ */
+function sleepSync(ms) {
+    const sab = new SharedArrayBuffer(4);
+    const ia = new Int32Array(sab);
+    Atomics.wait(ia, 0, 0, ms);
+}
+function subjectLockDir(artifactRoot, subjectId) {
+    const assignmentDir = path.join(artifactRoot, "assignment");
+    fs.mkdirSync(assignmentDir, { recursive: true });
+    const sanitized = loadActorIdentityHelper().sanitizeSegment(subjectId);
+    return path.join(assignmentDir, `.${sanitized}.lockdir`);
+}
+/**
+ * F1 fix (fix-plan iteration 1, CRITICAL): claimLocalFile/releaseLocalFile/supersedeLocalFile were
+ * a plain read -> compare-actor -> write with no lock, so two concurrently-launched OS processes
+ * could both read "no conflicting claim" before either wrote, and the second write would silently
+ * clobber the first with zero error and zero audit-trail entry for the loser (reproduced 29/40
+ * races against the built CLI). This mirrors the EXACT mechanism `withLock` already uses in
+ * workflow-sidecar.ts:908 for the same class of shared-state mutation — atomic `fs.mkdirSync`
+ * lockdir create as the mutual-exclusion primitive, EEXIST-spin with a staleness-reclaim check
+ * (a lock directory older than the stale threshold is presumed abandoned by a crashed process and
+ * is reclaimed rather than waited on forever) and a bounded deadline, `finally` rmSync release —
+ * as a small LOCAL helper (not a cross-import of that private function, which would pull the
+ * entire workflow-sidecar module in for one primitive). Deliberately synchronous (sleepSync's
+ * Atomics.wait spin, not setTimeout/await) so claim/release/supersede can stay sync `number`
+ * -returning functions and the CLI dispatcher (src/cli.ts, `number | Promise<number>`) does not
+ * need any ripple to async. On lock-acquire failure (any error other than a live contested lock,
+ * or a timeout waiting one out) this THROWS — never a silent no-op — "fail loud, never fail-open"
+ * (artifact-contract.md). Wrap the ENTIRE read-modify-write body (the existing-claim check AND
+ * the write) of all three local-file mutators in this, since all three mutate the same record
+ * file for a given subject.
+ */
+export function withSubjectLock(artifactRoot, subjectId, body) {
+    const lockDir = subjectLockDir(artifactRoot, subjectId);
+    const staleMs = Number(process.env.FLOW_AGENTS_ASSIGNMENT_STALE_LOCK_MS ?? 5 * 60 * 1000);
+    const deadline = Date.now() + 30000;
+    while (true) {
+        try {
+            fs.mkdirSync(lockDir);
+            break;
+        }
+        catch (error) {
+            const lockError = error;
+            if (lockError.code !== "EEXIST") {
+                throw new Error(`failed to acquire assignment lock for subject ${subjectId}: ${lockDir}: ${lockError.message || lockError.code || String(lockError)}`);
+            }
+            try {
+                const stat = fs.statSync(lockDir);
+                if (staleMs > 0 && Date.now() - stat.mtimeMs > staleMs) {
+                    fs.rmSync(lockDir, { recursive: true, force: true });
+                    continue;
+                }
+            }
+            catch (statError) {
+                if (statError.code === "ENOENT")
+                    continue; // lock released between mkdir/EEXIST and stat; retry immediately
+                throw statError;
+            }
+            if (Date.now() > deadline) {
+                throw new Error(`timed out waiting for assignment lock for subject ${subjectId}: ${lockDir}`);
+            }
+            sleepSync(20);
+        }
+    }
+    try {
+        return body();
+    }
+    finally {
+        fs.rmSync(lockDir, { recursive: true, force: true });
+    }
+}
+/**
+ * The assignment ⋈ liveness join (contract doc's "assignment ⋈ liveness join" section, ADR 0021
+ * §1). Pure function: `{ assignment, freshHoldersList, selfActor, nowMs }` -> one of five
+ * effective states (held/reclaimable/human-held/free — "held" covers both the plain and
+ * assignment-lagging rows, matching the contract table's own repeated "held" label).
+ *
+ * The human-assignee gate (AC11, Design Decision 3) reads `record.actor.human` being *present*,
+ * never a username heuristic — an idle human assignment is always `human-held`, regardless of
+ * idle duration, and is never auto-reclaimable by this function.
+ *
+ * `nowMs` (F3 fix, fix-plan iteration 1) is the SAME resolved "now" the caller already threads
+ * into `freshHolders()` (the `--now` override, when passed, else `Date.now()`) — passing it
+ * through here too means `--now` deterministically governs idle_days as well as liveness
+ * freshness, rather than idle_days silently reading the real wall clock regardless of `--now`.
+ */
+export function computeEffectiveState(assignment, freshHoldersList, selfActor, nowMs) {
+    const record = assignment.record && assignment.record.status === "claimed" ? assignment.record : null;
+    const isAssigned = Boolean(assignment.assignee) || Boolean(record);
+    if (!isAssigned) {
+        if (freshHoldersList.length > 0) {
+            const holder = freshHoldersList[0];
+            return { effective_state: "held", reason: "liveness_claim_present_assignment_lagging", holder: { actor: holder.actor, last_at: holder.lastAt } };
+        }
+        return { effective_state: "free", reason: "no_assignment_no_liveness" };
+    }
+    if (record && record.actor && record.actor.human != null && String(record.actor.human).trim() !== "") {
+        // F3 fix (fix-plan iteration 1): idle_days is computed from the SAME resolved `now` the
+        // caller already threads into freshHolders() (the `--now` override, when passed), not a
+        // second, independent Date.now() read — so `--now` governs both liveness freshness AND
+        // idle-based classification deterministically, rather than only the former.
+        const idleMs = nowMs - Date.parse(record.claimed_at);
+        const idleDays = Number.isFinite(idleMs) ? Math.floor(idleMs / 86_400_000) : null;
+        return { effective_state: "human-held", reason: "assignee_is_human", holder: { actor: assignment.assignee ?? undefined, idle_days: idleDays } };
+    }
+    if (!record) {
+        // Assignee present (e.g. a raw GitHub assignee) with no parseable machine claim record: we
+        // cannot positively identify this as a stale agent session, so the conservative ask-first
+        // default treats it the same as an explicit human assignment rather than risk reclaiming a
+        // human's work (Design Decision 3 / ADR 0021 §6's "never auto-reclaim" non-goal).
+        return { effective_state: "human-held", reason: "assignee_without_claim_record", holder: { assignee: assignment.assignee } };
+    }
+    // F1 fix (fix-plan iteration 1, HIGH): prefer the canonical actor_key over re-serializing
+    // record.actor. record.actor_key IS resolveActor(env).actor for records written by the fixed
+    // performLocalClaim/performLocalSupersede paths (below) — the same flat/bare string liveness
+    // whoami, `liveness claim --actor`, per-actor current.json, and pull-work's --self-actor all
+    // use — so for an explicit-override actor the self-check and the liveness join now agree with
+    // every other tool. BACK-COMPAT: records with no actor_key (every pre-fix record, every #290
+    // eval fixture) fall back to serializeActor(record.actor) exactly as before this fix.
+    const holderActorKey = record.actor_key || loadActorIdentityHelper().serializeActor(record.actor);
+    if (selfActor && holderActorKey === selfActor)
+        return { effective_state: "held", reason: "self_is_holder", holder: { actor: holderActorKey } };
+    const fresh = freshHoldersList.find((holder) => holder.actor === holderActorKey);
+    if (fresh)
+        return { effective_state: "held", reason: "fresh_liveness_heartbeat", holder: { actor: holderActorKey, last_at: fresh.lastAt } };
+    return { effective_state: "reclaimable", reason: "assignment_present_liveness_stale_or_absent", holder: { actor: holderActorKey, last_at: record.claimed_at } };
+}
+function namesOf(list, key) {
+    if (!Array.isArray(list))
+        return [];
+    return list.map((item) => typeof item === "string" ? item : (item && typeof item === "object" ? String(item[key] ?? "") : "")).filter(Boolean);
+}
+/**
+ * F2 fix (fix-plan iteration 1, HIGH): every string field on a GitHub claim record is sourced
+ * from a parsed, attacker-postable issue comment (any GitHub user who can comment can forge a
+ * claim-marker comment with a hostile fenced JSON block — commenting requires no elevated
+ * access, unlike the assignee/label mutations this contract otherwise gates). Mirrors
+ * workflow-sidecar.ts's `stripControlCharsForDisplay` (the established #287/#320 mitigation for
+ * exactly this class of untrusted multi-writer/attacker-postable display input): strips C0
+ * (0x00-0x1F), DEL (0x7F), and C1 (0x80-0x9F, which includes ANSI-CSI-adjacent bytes), then caps
+ * length (this repo's 64/240 convention: 64 for id-like fields, 240 for free text). Display-only
+ * — sanitizing the string CONTENT never changes presence/emptiness for any well-formed value, so
+ * it does not perturb computeEffectiveState()'s human-assignee presence gate or any equality
+ * check downstream.
+ */
+function sanitizeDisplayField(value, maxLength) {
+    const stripped = String(value ?? "").replace(/[\u0000-\u001F\u007F-\u009F]/g, "");
+    return stripped.length > maxLength ? stripped.slice(0, maxLength) : stripped;
+}
+function sanitizeActorForDisplay(actor) {
+    return {
+        runtime: sanitizeDisplayField(actor.runtime, 64),
+        session_id: sanitizeDisplayField(actor.session_id, 64),
+        host: sanitizeDisplayField(actor.host, 64),
+        human: actor.human != null ? sanitizeDisplayField(actor.human, 240) : (actor.human ?? null),
+    };
+}
+function sanitizeAuditEntryForDisplay(entry) {
+    return {
+        ...entry,
+        from_actor: entry.from_actor ? sanitizeActorForDisplay(entry.from_actor) : (entry.from_actor ?? null),
+        to_actor: entry.to_actor ? sanitizeActorForDisplay(entry.to_actor) : (entry.to_actor ?? null),
+        reason: entry.reason != null ? sanitizeDisplayField(entry.reason, 240) : entry.reason,
+    };
+}
+/**
+ * The single choke point (per the code review's explicit recommendation) every parsed GitHub
+ * claim record passes through before any string in it leaves this module in any form — both
+ * `status`/`list`'s JSON output (this fix) and any future consumer of `extractClaimRecord`'s
+ * return value inherit clean values from here, mirroring the #320 `computeConflict()` precedent
+ * of sanitizing once at construction rather than at each print site.
+ */
+function sanitizeClaimRecordForDisplay(record) {
+    return {
+        ...record,
+        subject_id: sanitizeDisplayField(record.subject_id, 64),
+        branch: sanitizeDisplayField(record.branch, 240),
+        artifact_dir: sanitizeDisplayField(record.artifact_dir, 240),
+        actor: sanitizeActorForDisplay(record.actor),
+        audit_trail: Array.isArray(record.audit_trail) ? record.audit_trail.map(sanitizeAuditEntryForDisplay) : record.audit_trail,
+    };
+}
+/**
+ * Locate the machine-readable claim comment among human comments (via the fixed marker) and
+ * extract/validate its fenced JSON block. Fails loud on an unparseable or misversioned record —
+ * never silently treats a corrupt comment as "no claim" (same rationale as readLocalRecord()).
+ * The returned record's display-surfaced string fields are sanitized (F2 fix, above) before
+ * return — this is the single choke point, so schema/role/status checks above still validate
+ * the RAW parsed shape (never weakened), and only the string fields are transformed afterward.
+ */
+function extractClaimRecord(issue, marker) {
+    const comments = Array.isArray(issue.comments) ? issue.comments : [];
+    for (const comment of comments) {
+        const body = String(comment.body ?? "");
+        const markerIndex = body.indexOf(marker);
+        if (markerIndex === -1)
+            continue;
+        const fenceMatch = body.slice(markerIndex).match(/```json\s*([\s\S]*?)```/);
+        if (!fenceMatch)
+            throw new Error(`claim comment (id ${comment.id ?? "?"}) has the claim marker but no fenced JSON block`);
+        let parsed;
+        try {
+            parsed = JSON.parse(fenceMatch[1]);
+        }
+        catch (error) {
+            throw new Error(`claim comment (id ${comment.id ?? "?"}) fenced JSON is unparseable: ${error.message}`);
+        }
+        if (typeof parsed !== "object" || parsed === null)
+            throw new Error(`claim comment (id ${comment.id ?? "?"}) fenced JSON is not an object`);
+        const record = parsed;
+        if (record.schema_version !== "1.0")
+            throw new Error(`claim comment (id ${comment.id ?? "?"}) has unsupported schema_version ${String(record.schema_version)}`);
+        if (record.role !== "AssignmentClaimRecord")
+            throw new Error(`claim comment (id ${comment.id ?? "?"}) has unexpected role ${String(record.role)}`);
+        return sanitizeClaimRecordForDisplay(record);
+    }
+    return null;
+}
+function githubAssignmentStatus(issue, labelName, marker) {
+    const assignees = namesOf(issue.assignees, "login");
+    const labels = namesOf(issue.labels, "name");
+    const record = extractClaimRecord(issue, marker);
+    return {
+        subject_id: record?.subject_id ?? "",
+        provider: "github",
+        assignee: assignees[0] ?? null,
+        record,
+        has_claim_label: labels.map((label) => label.toLowerCase()).includes(labelName.toLowerCase()),
+    };
+}
+function loadLivenessInputs(args) {
+    const eventsJsonPath = flagString(args.flags, "liveness-events-json");
+    const streamPath = flagString(args.flags, "liveness-stream");
+    const selfActor = flagString(args.flags, "self-actor");
+    if (eventsJsonPath) {
+        const data = loadJsonInput(eventsJsonPath);
+        if (!Array.isArray(data))
+            throw new Error(`--liveness-events-json must contain a JSON array: ${eventsJsonPath}`);
+        return { events: data, selfActor };
+    }
+    if (streamPath)
+        return { events: loadLivenessReadHelper().readLivenessEvents(streamPath), selfActor };
+    return { events: null, selfActor };
+}
+// ─── local-file: claim | release | supersede (the durable-write path; real I/O by design — no
+// external mutation to defer to a skill for this provider kind, per Design Decision 1) ─────────
+/**
+ * Wave 1 (#291) extraction: the durable-write body previously inlined inside claimLocalFile's
+ * withSubjectLock() closure, now a parameter-driven pure function so ensure-session's ownership
+ * guard (workflow-sidecar.ts, Wave 2) can reuse the EXACT same claim logic — same-actor idempotent
+ * refresh, different-actor throw, atomic write under withSubjectLock — rather than reimplementing
+ * a second, parallel claim path. claimLocalFile (CLI wrapper, below) is now a thin
+ * parse-args/print-envelope shell around this.
+ */
+export function performLocalClaim(artifactRoot, subjectId, actor, opts) {
+    const helper = loadActorIdentityHelper();
+    const reason = opts.reason ?? "claim";
+    // F1 fix (fix-plan iteration 1, CRITICAL): the existing-claim check AND the write must happen
+    // atomically with respect to any other `assignment-provider` invocation on the same subject —
+    // see withSubjectLock()'s doc comment for the full rationale.
+    return withSubjectLock(artifactRoot, subjectId, () => {
+        const existing = readLocalRecord(artifactRoot, subjectId);
+        if (existing && existing.status === "claimed") {
+            const existingActorKey = helper.serializeActor(existing.actor);
+            const newActorKey = helper.serializeActor(actor);
+            // AC7: a second claim from a different actor must never silently overwrite the first.
+            // Same actor re-claiming (refresh before TTL expiry) is allowed and idempotent.
+            if (existingActorKey !== newActorKey) {
+                throw new Error(`subject already claimed by a different actor: ${existingActorKey} (claimed_at ${existing.claimed_at}); refusing to overwrite — use supersede to reassign`);
+            }
+        }
+        const record = {
+            schema_version: "1.0",
+            role: "AssignmentClaimRecord",
+            subject_id: subjectId,
+            actor,
+            ...(opts.actorKey ? { actor_key: opts.actorKey } : {}),
+            claimed_at: isoNow(),
+            ttl_seconds: opts.ttlSeconds,
+            branch: opts.branch,
+            artifact_dir: opts.artifactDir,
+            status: "claimed",
+            audit_trail: [...(existing?.audit_trail ?? []), { at: isoNow(), transition: "claim", from_actor: null, to_actor: actor, reason }],
+        };
+        writeLocalRecord(artifactRoot, subjectId, record);
+        return record;
+    });
+}
+function claimLocalFile(argv) {
+    const args = parseArgs(argv);
+    const provider = flagString(args.flags, "provider", "local-file");
+    if (provider !== "local-file")
+        throw new Error(`claim: --provider must be local-file (use render-claim for github); got ${provider}`);
+    const artifactRoot = requireFlag(args, "artifact-root");
+    const subjectId = requireFlag(args, "subject-id");
+    const { actor, actorKey } = loadActorStruct(args);
+    const ttlSecondsRaw = flagString(args.flags, "ttl-seconds", "1800") ?? "1800";
+    const ttlSeconds = Number(ttlSecondsRaw);
+    if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0)
+        throw new Error(`--ttl-seconds must be a positive number; got ${ttlSecondsRaw}`);
+    const branch = requireFlag(args, "branch");
+    const artifactDir = requireFlag(args, "artifact-dir");
+    const reason = flagString(args.flags, "reason") ?? "claim";
+    const record = performLocalClaim(artifactRoot, subjectId, actor, { ttlSeconds, branch, artifactDir, reason, actorKey });
+    console.log(JSON.stringify({ role: "AssignmentClaimResult", subject_id: subjectId, record }, null, 2));
+    return 0;
+}
+function releaseLocalFile(argv) {
+    const args = parseArgs(argv);
+    const provider = flagString(args.flags, "provider", "local-file");
+    if (provider !== "local-file")
+        throw new Error(`release: --provider must be local-file (use render-release for github); got ${provider}`);
+    const artifactRoot = requireFlag(args, "artifact-root");
+    const subjectId = requireFlag(args, "subject-id");
+    const releasedBy = flagString(args.flags, "actor-json") ? loadActorStructFromFile(requireFlag(args, "actor-json")) : null;
+    const reason = flagString(args.flags, "reason") ?? "released";
+    // F1 fix (fix-plan iteration 1, CRITICAL): release mutates the same record file claim/supersede
+    // do, under the same per-subject lock (see withSubjectLock()'s doc comment).
+    return withSubjectLock(artifactRoot, subjectId, () => {
+        const existing = readLocalRecord(artifactRoot, subjectId);
+        if (!existing || existing.status !== "claimed")
+            throw new Error(`no active claim to release for subject: ${subjectId}`);
+        const record = {
+            ...existing,
+            status: "released",
+            audit_trail: [...(existing.audit_trail ?? []), { at: isoNow(), transition: "release", from_actor: existing.actor, to_actor: releasedBy, reason }],
+        };
+        writeLocalRecord(artifactRoot, subjectId, record);
+        console.log(JSON.stringify({ role: "AssignmentReleaseResult", subject_id: subjectId, record }, null, 2));
+        return 0;
+    });
+}
+/**
+ * Wave 1 (#291) extraction: the durable-write body previously inlined inside supersedeLocalFile's
+ * withSubjectLock() closure, now a parameter-driven pure function so ensure-session's
+ * `--supersede-stale` takeover path (workflow-sidecar.ts, Wave 2) can reuse the EXACT same
+ * supersede logic — from-actor holder verification, ttl/branch/artifact_dir carry-forward,
+ * audit-trail append, atomic write under withSubjectLock — rather than reimplementing a second,
+ * parallel supersede path. supersedeLocalFile (CLI wrapper, below) is now a thin
+ * parse-args/print-envelope shell around this.
+ */
+export function performLocalSupersede(artifactRoot, subjectId, fromActor, toActor, opts = {}) {
+    const helper = loadActorIdentityHelper();
+    const reason = opts.reason ?? "supersede";
+    // F1 fix (fix-plan iteration 1, CRITICAL): supersede mutates the same record file claim/release
+    // do, under the same per-subject lock (see withSubjectLock()'s doc comment).
+    return withSubjectLock(artifactRoot, subjectId, () => {
+        const existing = readLocalRecord(artifactRoot, subjectId);
+        if (!existing || existing.status !== "claimed")
+            throw new Error(`no active claim to supersede for subject: ${subjectId}`);
+        if (helper.serializeActor(existing.actor) !== helper.serializeActor(fromActor)) {
+            throw new Error(`--from-actor-json does not match the current holder (${helper.serializeActor(existing.actor)}); refusing to supersede a claim held by someone else`);
+        }
+        const ttlSecondsRaw = opts.ttlSeconds != null ? String(opts.ttlSeconds) : String(existing.ttl_seconds);
+        const ttlSeconds = Number(ttlSecondsRaw);
+        if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0)
+            throw new Error(`--ttl-seconds must be a positive number; got ${ttlSecondsRaw}`);
+        const record = {
+            schema_version: "1.0",
+            role: "AssignmentClaimRecord",
+            subject_id: subjectId,
+            actor: toActor,
+            ...(opts.actorKey ? { actor_key: opts.actorKey } : {}),
+            claimed_at: isoNow(),
+            ttl_seconds: ttlSeconds,
+            branch: opts.branch ?? existing.branch,
+            artifact_dir: opts.artifactDir ?? existing.artifact_dir,
+            status: "claimed",
+            audit_trail: [...(existing.audit_trail ?? []), { at: isoNow(), transition: "supersede", from_actor: fromActor, to_actor: toActor, reason }],
+        };
+        writeLocalRecord(artifactRoot, subjectId, record);
+        return record;
+    });
+}
+function supersedeLocalFile(argv) {
+    const args = parseArgs(argv);
+    const provider = flagString(args.flags, "provider", "local-file");
+    if (provider !== "local-file")
+        throw new Error(`supersede: --provider must be local-file (use render-supersede for github); got ${provider}`);
+    const artifactRoot = requireFlag(args, "artifact-root");
+    const subjectId = requireFlag(args, "subject-id");
+    const fromActor = loadActorStructFromFile(requireFlag(args, "from-actor-json"));
+    const toActor = loadActorStructFromFile(requireFlag(args, "to-actor-json"));
+    const reason = flagString(args.flags, "reason") ?? "supersede";
+    const ttlSecondsOverride = flagString(args.flags, "ttl-seconds");
+    const branchOverride = flagString(args.flags, "branch");
+    const artifactDirOverride = flagString(args.flags, "artifact-dir");
+    const record = performLocalSupersede(artifactRoot, subjectId, fromActor, toActor, {
+        ttlSeconds: ttlSecondsOverride != null ? Number(ttlSecondsOverride) : undefined,
+        branch: branchOverride ?? undefined,
+        artifactDir: artifactDirOverride ?? undefined,
+        reason,
+    });
+    console.log(JSON.stringify({ role: "AssignmentSupersedeResult", subject_id: subjectId, record }, null, 2));
+    return 0;
+}
+// ─── GitHub: render-claim | render-release | render-supersede (render, don't execute — Design
+// Decision 1). Pure functions: no I/O beyond reading --input-json/--actor-json. Never invoke
+// `gh` (or any process) here — the calling skill runs the emitted argv verbatim. ────────────────
+function requireRepo(input) {
+    const repo = input.repo;
+    if (!repo || !repo.owner || !repo.name)
+        throw new Error("input-json.repo.owner and input-json.repo.name are required");
+    return { owner: repo.owner, name: repo.name };
+}
+function requireIssueNumber(input) {
+    const issueNumber = input.issue_number;
+    if (!Number.isFinite(issueNumber))
+        throw new Error("input-json.issue_number is required");
+    return Number(issueNumber);
+}
+function renderClaimCommentBody(record, marker) {
+    const humanNote = record.actor.human ? `Assigned to human ${record.actor.human}.` : `Claimed by an automated agent session (${record.actor.runtime}).`;
+    return [
+        marker,
+        `**Assignment claim** — ${humanNote}`,
+        "",
+        `- actor: \`${loadActorIdentityHelper().serializeActor(record.actor)}\``,
+        `- claimed_at: ${record.claimed_at}`,
+        `- ttl_seconds: ${record.ttl_seconds}`,
+        `- branch: \`${record.branch}\``,
+        "",
+        "```json",
+        JSON.stringify(record, null, 2),
+        "```",
+    ].join("\n");
+}
+function renderHandoffCommentBody(subjectId, input) {
+    const marker = input.claim_comment_marker ?? CLAIM_COMMENT_MARKER_DEFAULT;
+    const record = input.previous_record
+        ? {
+            ...input.previous_record,
+            status: "released",
+            audit_trail: [...(input.previous_record.audit_trail ?? []), { at: isoNow(), transition: "release", from_actor: input.previous_record.actor, to_actor: null, reason: input.reason ?? "released" }],
+        }
+        : null;
+    const lines = [marker, `**Assignment released** — subject \`${subjectId}\` is free.`];
+    if (record)
+        lines.push("", "```json", JSON.stringify(record, null, 2), "```");
+    return lines.join("\n");
+}
+function renderClaim(argv) {
+    const args = parseArgs(argv);
+    const provider = flagString(args.flags, "provider", "github");
+    if (provider !== "github")
+        throw new Error(`render-claim: --provider must be github; got ${provider}`);
+    const subjectId = requireFlag(args, "subject-id");
+    const input = loadJsonInput(requireFlag(args, "input-json"));
+    const actor = loadActorStructFromFile(requireFlag(args, "actor-json"));
+    const repo = requireRepo(input);
+    const issueNumber = requireIssueNumber(input);
+    const labelName = input.label_name ?? DEFAULT_LABEL_NAME;
+    const marker = input.claim_comment_marker ?? CLAIM_COMMENT_MARKER_DEFAULT;
+    const ttlSeconds = input.ttl_seconds ?? 1800;
+    const branch = input.branch;
+    const artifactDir = input.artifact_dir;
+    if (!branch)
+        throw new Error("input-json.branch is required for render-claim");
+    if (!artifactDir)
+        throw new Error("input-json.artifact_dir is required for render-claim");
+    const record = {
+        schema_version: "1.0",
+        role: "AssignmentClaimRecord",
+        subject_id: subjectId,
+        actor,
+        claimed_at: isoNow(),
+        ttl_seconds: ttlSeconds,
+        branch,
+        artifact_dir: artifactDir,
+        status: "claimed",
+    };
+    const repoSlug = `${repo.owner}/${repo.name}`;
+    const commentBody = renderClaimCommentBody(record, marker);
+    const ghCommands = [];
+    if (input.assignee_login)
+        ghCommands.push(["gh", "issue", "edit", String(issueNumber), "--repo", repoSlug, "--add-assignee", input.assignee_login]);
+    ghCommands.push(["gh", "issue", "edit", String(issueNumber), "--repo", repoSlug, "--add-label", labelName]);
+    ghCommands.push(input.existing_comment_id
+        ? ["gh", "api", "--method", "PATCH", `repos/${repoSlug}/issues/comments/${input.existing_comment_id}`, "-f", `body=${commentBody}`]
+        : ["gh", "issue", "comment", String(issueNumber), "--repo", repoSlug, "--body", commentBody]);
+    console.log(JSON.stringify({ role: "AssignmentRenderResult", transition: "claim", subject_id: subjectId, gh_commands: ghCommands, claim_comment_body: commentBody, record }, null, 2));
+    return 0;
+}
+function renderRelease(argv) {
+    const args = parseArgs(argv);
+    const provider = flagString(args.flags, "provider", "github");
+    if (provider !== "github")
+        throw new Error(`render-release: --provider must be github; got ${provider}`);
+    const subjectId = requireFlag(args, "subject-id");
+    const input = loadJsonInput(requireFlag(args, "input-json"));
+    const repo = requireRepo(input);
+    const issueNumber = requireIssueNumber(input);
+    const labelName = input.label_name ?? DEFAULT_LABEL_NAME;
+    const repoSlug = `${repo.owner}/${repo.name}`;
+    const ghCommands = [];
+    const assigneeLogin = input.existing_assignee_login ?? input.assignee_login;
+    if (assigneeLogin)
+        ghCommands.push(["gh", "issue", "edit", String(issueNumber), "--repo", repoSlug, "--remove-assignee", assigneeLogin]);
+    ghCommands.push(["gh", "issue", "edit", String(issueNumber), "--repo", repoSlug, "--remove-label", labelName]);
+    const handoffBody = renderHandoffCommentBody(subjectId, input);
+    ghCommands.push(input.existing_comment_id
+        ? ["gh", "api", "--method", "PATCH", `repos/${repoSlug}/issues/comments/${input.existing_comment_id}`, "-f", `body=${handoffBody}`]
+        : ["gh", "issue", "comment", String(issueNumber), "--repo", repoSlug, "--body", handoffBody]);
+    console.log(JSON.stringify({ role: "AssignmentRenderResult", transition: "release", subject_id: subjectId, gh_commands: ghCommands, claim_comment_body: handoffBody }, null, 2));
+    return 0;
+}
+function renderSupersede(argv) {
+    const args = parseArgs(argv);
+    const provider = flagString(args.flags, "provider", "github");
+    if (provider !== "github")
+        throw new Error(`render-supersede: --provider must be github; got ${provider}`);
+    const subjectId = requireFlag(args, "subject-id");
+    const input = loadJsonInput(requireFlag(args, "input-json"));
+    const toActor = loadActorStructFromFile(requireFlag(args, "actor-json"));
+    const repo = requireRepo(input);
+    const issueNumber = requireIssueNumber(input);
+    const labelName = input.label_name ?? DEFAULT_LABEL_NAME;
+    const marker = input.claim_comment_marker ?? CLAIM_COMMENT_MARKER_DEFAULT;
+    const ttlSeconds = input.ttl_seconds ?? 1800;
+    const branch = input.branch;
+    const artifactDir = input.artifact_dir;
+    if (!branch)
+        throw new Error("input-json.branch is required for render-supersede");
+    if (!artifactDir)
+        throw new Error("input-json.artifact_dir is required for render-supersede");
+    // Wave 4 AC: render-supersede must edit the existing claim comment in place, never duplicate it.
+    if (!input.existing_comment_id)
+        throw new Error("input-json.existing_comment_id is required for render-supersede (edits the claim comment in place; never duplicates it)");
+    const previousActor = input.previous_record?.actor ?? null;
+    const record = {
+        schema_version: "1.0",
+        role: "AssignmentClaimRecord",
+        subject_id: subjectId,
+        actor: toActor,
+        claimed_at: isoNow(),
+        ttl_seconds: ttlSeconds,
+        branch,
+        artifact_dir: artifactDir,
+        status: "claimed",
+        audit_trail: [...(input.previous_record?.audit_trail ?? []), { at: isoNow(), transition: "supersede", from_actor: previousActor, to_actor: toActor, reason: input.reason ?? "supersede" }],
+    };
+    const repoSlug = `${repo.owner}/${repo.name}`;
+    const commentBody = renderClaimCommentBody(record, marker);
+    const ghCommands = [];
+    const previousAssignee = input.existing_assignee_login;
+    if (previousAssignee && previousAssignee !== input.assignee_login)
+        ghCommands.push(["gh", "issue", "edit", String(issueNumber), "--repo", repoSlug, "--remove-assignee", previousAssignee]);
+    if (input.assignee_login)
+        ghCommands.push(["gh", "issue", "edit", String(issueNumber), "--repo", repoSlug, "--add-assignee", input.assignee_login]);
+    ghCommands.push(["gh", "issue", "edit", String(issueNumber), "--repo", repoSlug, "--add-label", labelName]);
+    ghCommands.push(["gh", "api", "--method", "PATCH", `repos/${repoSlug}/issues/comments/${input.existing_comment_id}`, "-f", `body=${commentBody}`]);
+    console.log(JSON.stringify({ role: "AssignmentRenderResult", transition: "supersede", subject_id: subjectId, gh_commands: ghCommands, claim_comment_body: commentBody, record }, null, 2));
+    return 0;
+}
+// ─── status | list (both provider kinds) ────────────────────────────────────────────────────
+/**
+ * Wave 1 (#291) extraction: the local-file branch of statusCommand's assignment-layer read,
+ * mirrored exactly so ensure-session's ownership guard (workflow-sidecar.ts, Wave 2) derives an
+ * AssignmentStatus identically to the `assignment-provider status` CLI command — a single
+ * implementation, not a second parallel local-file read.
+ */
+export function readLocalAssignmentStatus(artifactRoot, subjectId) {
+    const record = readLocalRecord(artifactRoot, subjectId);
+    const active = record && record.status === "claimed" ? record : null;
+    return { subject_id: subjectId, provider: "local-file", assignee: active ? loadActorIdentityHelper().serializeActor(active.actor) : null, record: active };
+}
+function statusCommand(argv) {
+    const args = parseArgs(argv);
+    const provider = requireFlag(args, "provider");
+    const requestedSubjectId = flagString(args.flags, "subject-id");
+    let assignment;
+    if (provider === "local-file") {
+        const artifactRoot = requireFlag(args, "artifact-root");
+        if (!requestedSubjectId)
+            throw new Error("--subject-id is required for status --provider local-file");
+        assignment = readLocalAssignmentStatus(artifactRoot, requestedSubjectId);
+    }
+    else if (provider === "github") {
+        const issueJsonPath = requireFlag(args, "issue-json");
+        const issue = loadJsonInput(issueJsonPath);
+        const labelName = flagString(args.flags, "label-name", DEFAULT_LABEL_NAME) ?? DEFAULT_LABEL_NAME;
+        const marker = flagString(args.flags, "claim-comment-marker", CLAIM_COMMENT_MARKER_DEFAULT) ?? CLAIM_COMMENT_MARKER_DEFAULT;
+        assignment = githubAssignmentStatus(issue, labelName, marker);
+        if (requestedSubjectId && assignment.record && assignment.record.subject_id !== requestedSubjectId) {
+            throw new Error(`claim record subject_id ${assignment.record.subject_id} does not match requested --subject-id ${requestedSubjectId}`);
+        }
+        if (requestedSubjectId)
+            assignment.subject_id = requestedSubjectId;
+    }
+    else {
+        throw new Error(`status: unsupported --provider ${provider}`);
+    }
+    const { events, selfActor } = loadLivenessInputs(args);
+    const nowMs = flagString(args.flags, "now") ? Date.parse(flagString(args.flags, "now")) : Date.now();
+    const freshList = events !== null ? loadLivenessReadHelper().freshHolders(events, assignment.subject_id, selfActor ?? "", nowMs) : [];
+    const effective = events !== null
+        ? computeEffectiveState(assignment, freshList, selfActor, nowMs)
+        : { effective_state: null, reason: "liveness input not provided (pass --liveness-events-json or --liveness-stream); effective state not computed" };
+    console.log(JSON.stringify({ role: "AssignmentStatus", provider, assignment, effective }, null, 2));
+    return 0;
+}
+function listCommand(argv) {
+    const args = parseArgs(argv);
+    const provider = requireFlag(args, "provider");
+    const actorJsonFilter = flagString(args.flags, "actor-json");
+    const actorFilter = actorJsonFilter ? loadActorIdentityHelper().serializeActor(loadActorStructFromFile(actorJsonFilter)) : flagString(args.flags, "actor");
+    const subjectIds = [];
+    if (provider === "local-file") {
+        const artifactRoot = requireFlag(args, "artifact-root");
+        const dir = path.join(artifactRoot, "assignment");
+        const files = fs.existsSync(dir) ? fs.readdirSync(dir).filter((name) => name.endsWith(".json")).sort() : [];
+        for (const name of files) {
+            const record = readJson(path.join(dir, name));
+            if (record.status !== "claimed")
+                continue;
+            if (actorFilter && loadActorIdentityHelper().serializeActor(record.actor) !== actorFilter)
+                continue;
+            subjectIds.push(record.subject_id);
+        }
+    }
+    else if (provider === "github") {
+        const issuesJsonPath = requireFlag(args, "issues-json");
+        const doc = loadJsonInput(issuesJsonPath);
+        const issues = Array.isArray(doc) ? doc : (doc.items ?? []);
+        const labelName = flagString(args.flags, "label-name", DEFAULT_LABEL_NAME) ?? DEFAULT_LABEL_NAME;
+        const marker = flagString(args.flags, "claim-comment-marker", CLAIM_COMMENT_MARKER_DEFAULT) ?? CLAIM_COMMENT_MARKER_DEFAULT;
+        for (const issue of issues) {
+            const assignment = githubAssignmentStatus(issue, labelName, marker);
+            if (!assignment.record || assignment.record.status !== "claimed")
+                continue;
+            if (actorFilter && loadActorIdentityHelper().serializeActor(assignment.record.actor) !== actorFilter)
+                continue;
+            subjectIds.push(assignment.record.subject_id);
+        }
+    }
+    else {
+        throw new Error(`list: unsupported --provider ${provider}`);
+    }
+    console.log(JSON.stringify({ role: "AssignmentList", provider, actor: actorFilter ?? null, subject_ids: subjectIds }, null, 2));
+    return 0;
+}
+export function main(argv = process.argv.slice(2)) {
+    try {
+        const [command, ...rest] = argv;
+        if (command === "claim")
+            return claimLocalFile(rest);
+        if (command === "release")
+            return releaseLocalFile(rest);
+        if (command === "supersede")
+            return supersedeLocalFile(rest);
+        if (command === "render-claim")
+            return renderClaim(rest);
+        if (command === "render-release")
+            return renderRelease(rest);
+        if (command === "render-supersede")
+            return renderSupersede(rest);
+        if (command === "status")
+            return statusCommand(rest);
+        if (command === "list")
+            return listCommand(rest);
+        console.error("usage: assignment-provider <claim|release|supersede|render-claim|render-release|render-supersede|status|list> [flags]");
+        return 2;
+    }
+    catch (error) {
+        console.error(`assignment-provider: ${error.message}`);
+        return 1;
+    }
+}
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try {
+    return fs.realpathSync(fileURLToPath(import.meta.url));
+}
+catch {
+    return fileURLToPath(import.meta.url);
+} })();
+const _argv1RealPath = (() => { try {
+    return fs.realpathSync(process.argv[1]);
+}
+catch {
+    return process.argv[1];
+} })();
+if (_selfRealPath === _argv1RealPath) {
+    process.exitCode = main();
+}