@momentiq/dark-factory-cli 0.7.0-alpha.9 → 1.0.0

package/dist/handoff/ports.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Raised by the core for every operator-facing refusal/abort (the bash
+ * `die`). Carries an optional `savedNotePath` so the CLI can echo where a
+ * composed note was preserved when a push/gate blocked it (Decision D5 —
+ * the reasoning is the precious artifact and is never discarded).
+ */
+export declare class HandoffError extends Error {
+    readonly savedNotePath: string | undefined;
+    constructor(message: string, savedNotePath?: string);
+}
+export interface IssueView {
+    readonly number: number;
+    readonly title: string;
+    readonly body: string;
+    readonly state: "OPEN" | "CLOSED";
+    readonly assignees: ReadonlyArray<{
+        readonly login: string;
+    }>;
+    readonly labels: ReadonlyArray<{
+        readonly name: string;
+    }>;
+    readonly updatedAt: string;
+    readonly closedAt: string | null;
+}
+/**
+ * Subset of IssueView fields for drift/race checks (assignees + state +
+ * updatedAt; body omitted). Separate seam from issueView so the fake's
+ * ordinal counters split: _body-bearing_ vs _drift-only_ calls increment
+ * independently (mirrors bash's `issue_view_body` vs `issue_view` counter
+ * namespaces in tests/bin/gh).
+ */
+export interface IssueViewSlim {
+    readonly state: "OPEN" | "CLOSED";
+    readonly assignees: ReadonlyArray<{
+        readonly login: string;
+    }>;
+    readonly updatedAt: string;
+    /** body is optional — the drift check may skip it. */
+    readonly body?: string;
+}
+export interface PrView {
+    readonly title: string;
+    readonly state: "OPEN" | "CLOSED" | "MERGED";
+    readonly mergeStateStatus: string;
+    readonly reviewDecision: string;
+    readonly statusCheckRollup: ReadonlyArray<{
+        readonly conclusion?: string;
+        readonly state?: string;
+        readonly status?: string;
+    }>;
+}
+export interface IssueListItem {
+    readonly number: number;
+    readonly title: string;
+    readonly assignees: ReadonlyArray<{
+        readonly login: string;
+    }>;
+    readonly body?: string;
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    readonly closedAt?: string;
+}
+export interface IssueCreated {
+    readonly number: number;
+    readonly url: string;
+}
+export interface GhClient {
+    /** `gh auth status` — throws on non-zero. */
+    authStatus(): Promise<void>;
+    /** `gh api user --jq .login` */
+    apiUserLogin(): Promise<string>;
+    /** `gh label create handoff …` (idempotent — failure not fatal) */
+    ensureHandoffLabel(): Promise<void>;
+    /** `gh issue view <n> --json <full set>` — full IssueView (body included) */
+    issueView(num: number, opts?: {
+        repo?: string;
+    }): Promise<IssueView>;
+    /** Same fields minus body (separate seam for drift checks). */
+    issueViewSlim(num: number, opts?: {
+        repo?: string;
+    }): Promise<IssueViewSlim>;
+    /** `gh issue list --label handoff --state <s> ...` */
+    issueList(opts: {
+        state: "open" | "closed";
+        assignee?: "@me" | string;
+        search?: string;
+    }): Promise<readonly IssueListItem[]>;
+    /** `gh issue create --title <t> --body-file - --label handoff` */
+    issueCreate(opts: {
+        title: string;
+        bodyMd: string;
+        label: string;
+    }): Promise<IssueCreated>;
+    /** `gh issue edit <n> --body-file -` */
+    issueEditBody(num: number, bodyMd: string): Promise<void>;
+    /** `gh issue edit <n> --add-label <l>` */
+    issueAddLabel(num: number, label: string): Promise<void>;
+    /** `gh issue edit <n> --add-assignee @me` */
+    issueAssignMe(num: number): Promise<void>;
+    /** `gh issue edit <n> --remove-assignee @me` — idempotent; throws only on REAL gh errors. */
+    issueUnassignMe(num: number): Promise<void>;
+    /** `gh issue close <n>` */
+    issueClose(num: number): Promise<void>;
+    /** `gh pr view <n> --json state,mergeStateStatus,reviewDecision,statusCheckRollup,title` */
+    prView(num: number, opts?: {
+        repo?: string;
+    }): Promise<PrView>;
+    /** `gh pr list --head <branch> --state open --json number,title` */
+    prListByHead(branch: string): Promise<ReadonlyArray<{
+        number: number;
+        title: string;
+    }>>;
+}
+export interface GitClient {
+    /** `git rev-parse --abbrev-ref HEAD` — returns "HEAD" on detached. */
+    currentBranch(): Promise<string>;
+    /** True iff `git diff --quiet` OR `git diff --cached --quiet` returns non-zero. */
+    isDirty(): Promise<boolean>;
+}
+export interface Clock {
+    /** Epoch seconds (Unix). */
+    nowEpoch(): number;
+    /** YYYY-MM-DD in UTC. */
+    todayYmd(): string;
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/handoff/ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../src/handoff/ports.ts"],"names":[],"mappings":"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"}

package/dist/handoff/ports.js

@@ -0,0 +1,34 @@
+// packages/cli/src/handoff/ports.ts
+//
+// Hexagonal ports: GhClient + GitClient + Clock. All side-effecting verbs
+// take these as parameters; tests inject queue-based fakes (see
+// tests/handoff/fixtures/stubs/), production uses real-clients.ts which
+// spawns gh/git.
+//
+// The GhClient surface is fine-grained per gh idiom (one method per gh
+// verb pattern the bash uses) so the test fake can ordinal-key responses
+// per-method, mirroring bash's _bump_counter + STUB_ISSUE_BODY_N seam.
+// The verb impl is constrained to call these in the SAME ORDER the bash
+// did — drift/race tests assert that order (see advisor finding #2).
+//
+// HandoffError is the SINGLE class identity used across every v2 throw
+// site (verbs + ports + clients). Defined here (the lowest leaf in the
+// handoff module graph) so the new public surface (./index.js, Task 23)
+// can re-export from here without a cycle. The v1 monolith used to own
+// this class — Task 22 inverted the re-export when the v1 index.ts was
+// deleted, so this is now the canonical definition.
+/**
+ * Raised by the core for every operator-facing refusal/abort (the bash
+ * `die`). Carries an optional `savedNotePath` so the CLI can echo where a
+ * composed note was preserved when a push/gate blocked it (Decision D5 —
+ * the reasoning is the precious artifact and is never discarded).
+ */
+export class HandoffError extends Error {
+    savedNotePath;
+    constructor(message, savedNotePath) {
+        super(message);
+        this.name = "HandoffError";
+        this.savedNotePath = savedNotePath;
+    }
+}
+//# sourceMappingURL=ports.js.map

package/dist/handoff/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../../src/handoff/ports.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,EAAE;AACF,0EAA0E;AAC1E,gEAAgE;AAChE,wEAAwE;AACxE,iBAAiB;AACjB,EAAE;AACF,uEAAuE;AACvE,yEAAyE;AACzE,uEAAuE;AACvE,wEAAwE;AACxE,qEAAqE;AACrE,EAAE;AACF,uEAAuE;AACvE,uEAAuE;AACvE,wEAAwE;AACxE,uEAAuE;AACvE,uEAAuE;AACvE,oDAAoD;AAEpD;;;;;GAKG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,aAAa,CAAqB;IAC3C,YAAY,OAAe,EAAE,aAAsB;QACjD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACrC,CAAC;CACF"}

package/dist/handoff/real-clients.d.ts

@@ -0,0 +1,43 @@
+import type { Clock, GhClient, GitClient, IssueCreated, IssueListItem, IssueView, IssueViewSlim, PrView } from "./ports.js";
+export declare class SpawnGhClient implements GhClient {
+    authStatus(): Promise<void>;
+    apiUserLogin(): Promise<string>;
+    ensureHandoffLabel(): Promise<void>;
+    issueView(num: number, opts?: {
+        repo?: string;
+    }): Promise<IssueView>;
+    issueViewSlim(num: number, opts?: {
+        repo?: string;
+    }): Promise<IssueViewSlim>;
+    issueList(opts: {
+        state: "open" | "closed";
+        assignee?: "@me" | string;
+        search?: string;
+    }): Promise<readonly IssueListItem[]>;
+    issueCreate(opts: {
+        title: string;
+        bodyMd: string;
+        label: string;
+    }): Promise<IssueCreated>;
+    issueEditBody(num: number, bodyMd: string): Promise<void>;
+    issueAddLabel(num: number, label: string): Promise<void>;
+    issueAssignMe(num: number): Promise<void>;
+    issueUnassignMe(num: number): Promise<void>;
+    issueClose(num: number): Promise<void>;
+    prView(num: number, opts?: {
+        repo?: string;
+    }): Promise<PrView>;
+    prListByHead(branch: string): Promise<ReadonlyArray<{
+        number: number;
+        title: string;
+    }>>;
+}
+export declare class SpawnGitClient implements GitClient {
+    currentBranch(): Promise<string>;
+    isDirty(): Promise<boolean>;
+}
+export declare class SystemClock implements Clock {
+    nowEpoch(): number;
+    todayYmd(): string;
+}
+//# sourceMappingURL=real-clients.d.ts.map

package/dist/handoff/real-clients.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"real-clients.d.ts","sourceRoot":"","sources":["../../src/handoff/real-clients.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EACV,KAAK,EACL,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,aAAa,EACb,SAAS,EACT,aAAa,EACb,MAAM,EACP,MAAM,YAAY,CAAC;AAuGpB,qBAAa,aAAc,YAAW,QAAQ;IACtC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAS3B,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAc/B,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;IAanC,SAAS,CACb,GAAG,EAAE,MAAM,EACX,IAAI,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO,GAC3B,OAAO,CAAC,SAAS,CAAC;IAWf,aAAa,CACjB,GAAG,EAAE,MAAM,EACX,IAAI,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO,GAC3B,OAAO,CAAC,aAAa,CAAC;IAQnB,SAAS,CAAC,IAAI,EAAE;QACpB,KAAK,EAAE,MAAM,GAAG,QAAQ,CAAC;QACzB,QAAQ,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;QAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC;IAmB/B,WAAW,CAAC,IAAI,EAAE;QACtB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;KACf,GAAG,OAAO,CAAC,YAAY,CAAC;IAiCnB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUzD,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOxD,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOzC,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2B3C,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOtC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAWlE,YAAY,CAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,aAAa,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAgB7D;AAMD,qBAAa,cAAe,YAAW,SAAS;IACxC,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAQhC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;CAMlC;AAMD,qBAAa,WAAY,YAAW,KAAK;IACvC,QAAQ,IAAI,MAAM;IAIlB,QAAQ,IAAI,MAAM;CAOnB"}

package/dist/handoff/real-clients.js

@@ -0,0 +1,291 @@
+// packages/cli/src/handoff/real-clients.ts
+//
+// Production spawn-based implementations of the GhClient + GitClient + Clock
+// ports. Tests use the queue-based FakeGhClient/FakeGitClient/FixedClock
+// from tests/handoff/fixtures/stubs/ (Task 8) — these clients are exercised
+// end-to-end by the verb tests (Tasks 17-20) and live-smoke (Task 32).
+//
+// The spawn pattern mirrors the Cycle 8 v1 defaultExec in index.ts:50-120,
+// consolidated here as the home for the production clients. Two deliberate
+// divergences from v1:
+//
+//   1. v1 resolves {code:127} on ENOENT and a separate requireTools() layer
+//      translates 127 → HandoffError. The standalone clients here throw
+//      HandoffError DIRECTLY from exec() on ENOENT — there is no
+//      requireTools wrapper in the hexagonal seam. Consequence:
+//      currentBranch/isDirty/issueUnassignMe still swallow non-zero exit
+//      codes (their intended behavior), but throw if gh/git is entirely
+//      absent — which is the correct distinction (missing binary ≠ "clean
+//      tree"/"not assigned"). v1 is deleted in Task 22.
+//   2. The bash-side issueUnassignMe was idempotent on "not assigned"
+//      stderr (handoff.sh, the `*"not assigned"*` case). Mirrored here.
+//
+// HandoffError is imported as a VALUE (since we throw it); everything else
+// is type-only. ports.ts re-exports HandoffError from ./index.js for the
+// Tasks 11-22 window — Task 22 inverts that to put the class here in ports.
+import { spawn } from "node:child_process";
+import { HandoffError } from "./ports.js";
+const MAX_BUFFER = 64 * 1024 * 1024;
+/**
+ * Spawn helper. Resolves with {code, stdout, stderr} regardless of process
+ * exit status. Rejects ONLY on spawn-time errors — and an ENOENT (binary
+ * not on PATH) is translated into a HandoffError with an actionable
+ * "install …" message so the operator sees the fix path, not a raw Node
+ * error.
+ *
+ * SECURITY: this uses `child_process.spawn` with an argument-array form
+ * (no shell, no string interpolation). NOT `child_process.exec` — the
+ * local helper is named `exec` because it returns an ExecResult, not
+ * because it shells out. There is no shell process; arguments go
+ * directly to the child binary, so shell metacharacters in user input
+ * are inert. The bin name itself is a fixed literal ("gh"/"git").
+ *
+ * `spawn` (not `execFile`/`promisify`) is mandatory: some calls pipe a
+ * body to `--body-file -` on the child's STDIN. promisify(execFile)'s
+ * `input` option is silently dropped (it's exec-only), which would send
+ * EMPTY input and hang the child waiting on EOF.
+ */
+function exec(bin, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(bin, [...args], {
+            stdio: [options.input !== undefined ? "pipe" : "ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let overflow = false;
+        child.stdout?.on("data", (chunk) => {
+            if (stdout.length < MAX_BUFFER)
+                stdout += chunk.toString("utf8");
+            else
+                overflow = true;
+        });
+        child.stderr?.on("data", (chunk) => {
+            if (stderr.length < MAX_BUFFER)
+                stderr += chunk.toString("utf8");
+        });
+        child.on("error", (err) => {
+            const nodeErr = err;
+            if (nodeErr.code === "ENOENT") {
+                reject(new HandoffError(bin === "gh"
+                    ? "gh not found — install GitHub CLI and run 'gh auth login'."
+                    : `${bin} not found — install ${bin}.`));
+                return;
+            }
+            reject(err);
+        });
+        child.on("close", (code) => {
+            resolve({
+                code: overflow ? 1 : (code ?? 1),
+                stdout,
+                stderr,
+            });
+        });
+        if (options.input !== undefined && child.stdin) {
+            child.stdin.on("error", () => {
+                // EPIPE if the child exits before reading stdin — non-fatal; the
+                // close handler reports the real exit code.
+            });
+            child.stdin.end(options.input);
+        }
+    });
+}
+function gh(args, options = {}) {
+    return exec("gh", args, options);
+}
+function git(args) {
+    return exec("git", args);
+}
+/** Throw HandoffError with stderr text on non-zero exit; return on ok. */
+function expectOk(result, context) {
+    if (result.code !== 0) {
+        const stderr = result.stderr.trim() || "(no stderr)";
+        throw new HandoffError(`${context} failed (exit ${result.code}): ${stderr}`);
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// SpawnGhClient — 14 methods covering every gh verb pattern the bash uses.
+// ---------------------------------------------------------------------------
+export class SpawnGhClient {
+    async authStatus() {
+        const r = await gh(["auth", "status"]);
+        if (r.code !== 0) {
+            throw new HandoffError("gh not authenticated — run 'gh auth login'.");
+        }
+    }
+    async apiUserLogin() {
+        const r = expectOk(await gh(["api", "user", "--jq", ".login"]), "gh api user");
+        const login = r.stdout.trim();
+        if (!login) {
+            throw new HandoffError("could not determine @me's login (gh api user returned empty) — run 'gh auth status'.");
+        }
+        return login;
+    }
+    async ensureHandoffLabel() {
+        // Idempotent: never fatal. gh returns non-zero if the label exists.
+        await gh([
+            "label",
+            "create",
+            "handoff",
+            "--description",
+            "Agent handoff (Cycle 12 protocol)",
+            "--color",
+            "cccccc",
+        ]);
+    }
+    async issueView(num, opts = {}) {
+        const args = ["issue", "view", String(num)];
+        if (opts.repo)
+            args.push("--repo", opts.repo);
+        args.push("--json", "number,title,body,state,assignees,labels,updatedAt,closedAt");
+        const r = expectOk(await gh(args), `gh issue view ${num}`);
+        return JSON.parse(r.stdout);
+    }
+    async issueViewSlim(num, opts = {}) {
+        const args = ["issue", "view", String(num)];
+        if (opts.repo)
+            args.push("--repo", opts.repo);
+        args.push("--json", "state,assignees,updatedAt");
+        const r = expectOk(await gh(args), `gh issue view ${num} (slim)`);
+        return JSON.parse(r.stdout);
+    }
+    async issueList(opts) {
+        const args = [
+            "issue",
+            "list",
+            "--label",
+            "handoff",
+            "--state",
+            opts.state,
+        ];
+        if (opts.assignee)
+            args.push("--assignee", opts.assignee);
+        if (opts.search)
+            args.push("--search", opts.search);
+        args.push("--json", "number,title,assignees,body,createdAt,updatedAt,closedAt");
+        const r = expectOk(await gh(args), "gh issue list");
+        return JSON.parse(r.stdout);
+    }
+    async issueCreate(opts) {
+        const args = [
+            "issue",
+            "create",
+            "--title",
+            opts.title,
+            "--label",
+            opts.label,
+            "--body-file",
+            "-",
+        ];
+        const r = await gh(args, { input: opts.bodyMd });
+        if (r.code !== 0) {
+            throw new HandoffError(`gh issue create failed (exit ${r.code}): ${r.stderr.trim() || r.stdout.trim() || "(no output)"}`);
+        }
+        // gh issue create prints the URL on stdout (last non-empty line).
+        const lines = r.stdout
+            .trim()
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+        const url = lines[lines.length - 1] ?? "";
+        const match = url.match(/\/issues\/(\d+)\b/);
+        if (!match) {
+            throw new HandoffError(`could not parse issue number from \`gh issue create\` output: ${r.stdout.trim()}`);
+        }
+        return { number: Number(match[1]), url };
+    }
+    async issueEditBody(num, bodyMd) {
+        const args = ["issue", "edit", String(num), "--body-file", "-"];
+        const r = await gh(args, { input: bodyMd });
+        if (r.code !== 0) {
+            throw new HandoffError(`gh issue edit ${num} --body-file failed (exit ${r.code}): ${r.stderr.trim() || "(no stderr)"}`);
+        }
+    }
+    async issueAddLabel(num, label) {
+        expectOk(await gh(["issue", "edit", String(num), "--add-label", label]), `gh issue edit ${num} --add-label ${label}`);
+    }
+    async issueAssignMe(num) {
+        expectOk(await gh(["issue", "edit", String(num), "--add-assignee", "@me"]), `gh issue edit ${num} --add-assignee @me`);
+    }
+    async issueUnassignMe(num) {
+        // Bash parity: handoff.sh treats "not assigned" stderr as idempotent
+        // success (same case-arm in the shell version). Mirror that here so
+        // /handoff on a PR that's no longer assigned to @me is a no-op rather
+        // than an error.
+        const r = await gh([
+            "issue",
+            "edit",
+            String(num),
+            "--remove-assignee",
+            "@me",
+        ]);
+        if (r.code !== 0) {
+            const stderr = r.stderr;
+            if (/not assigned/i.test(stderr) ||
+                /could not assign/i.test(stderr) ||
+                /cannot remove/i.test(stderr)) {
+                return; // idempotent no-op
+            }
+            throw new HandoffError(`gh issue edit ${num} --remove-assignee @me failed: ${stderr.trim() || "(no stderr)"}`);
+        }
+    }
+    async issueClose(num) {
+        expectOk(await gh(["issue", "close", String(num)]), `gh issue close ${num}`);
+    }
+    async prView(num, opts = {}) {
+        const args = ["pr", "view", String(num)];
+        if (opts.repo)
+            args.push("--repo", opts.repo);
+        args.push("--json", "state,mergeStateStatus,reviewDecision,statusCheckRollup,title");
+        const r = expectOk(await gh(args), `gh pr view ${num}`);
+        return JSON.parse(r.stdout);
+    }
+    async prListByHead(branch) {
+        const r = expectOk(await gh([
+            "pr",
+            "list",
+            "--head",
+            branch,
+            "--state",
+            "open",
+            "--json",
+            "number,title",
+        ]), `gh pr list --head ${branch}`);
+        return JSON.parse(r.stdout);
+    }
+}
+// ---------------------------------------------------------------------------
+// SpawnGitClient — currentBranch + isDirty.
+// ---------------------------------------------------------------------------
+export class SpawnGitClient {
+    async currentBranch() {
+        const r = await git(["rev-parse", "--abbrev-ref", "HEAD"]);
+        // Non-zero (e.g., not in a repo) → fall back to "HEAD" so callers
+        // get a stable string rather than an exception. ENOENT (git missing)
+        // still throws from exec().
+        return r.code === 0 ? r.stdout.trim() || "HEAD" : "HEAD";
+    }
+    async isDirty() {
+        const unstaged = await git(["diff", "--quiet"]);
+        if (unstaged.code !== 0)
+            return true;
+        const staged = await git(["diff", "--cached", "--quiet"]);
+        return staged.code !== 0;
+    }
+}
+// ---------------------------------------------------------------------------
+// SystemClock — wall clock for format_age + create-title date.
+// ---------------------------------------------------------------------------
+export class SystemClock {
+    nowEpoch() {
+        return Math.floor(Date.now() / 1000);
+    }
+    todayYmd() {
+        const d = new Date();
+        const y = d.getUTCFullYear();
+        const m = String(d.getUTCMonth() + 1).padStart(2, "0");
+        const day = String(d.getUTCDate()).padStart(2, "0");
+        return `${y}-${m}-${day}`;
+    }
+}
+//# sourceMappingURL=real-clients.js.map

package/dist/handoff/real-clients.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"real-clients.js","sourceRoot":"","sources":["../../src/handoff/real-clients.ts"],"names":[],"mappings":"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"}

package/dist/handoff/rehydrate-core.d.ts

@@ -0,0 +1,55 @@
+import { type GhClient } from "./ports.js";
+export interface LinkedItemDerivation {
+    readonly kind: "pr" | "issue" | "?";
+    readonly display: string;
+    readonly title: string;
+    readonly state: "OPEN" | "CLOSED" | "MERGED" | "UNREACHABLE";
+    /** Human annotation: "", "(merged)", "(closed)",
+     * "(unreachable: gh pr view failed)" / "(unreachable: gh issue view failed)",
+     * "[open]", "[open, assigned X]", "(unknown link type)". */
+    readonly annotation: string;
+    /** Present for OPEN PRs only — copy-pastable `gh pr checkout N [--repo owner/repo]`. */
+    readonly checkoutHint?: string;
+    /** Extra fields for OPEN PRs (mergeStateStatus/reviewDecision/checksSummary)
+     * or OPEN issues (assigneesCsv). Absent for MERGED/CLOSED/UNREACHABLE. */
+    readonly extra?: {
+        readonly mergeStateStatus?: string;
+        readonly reviewDecision?: string;
+        readonly checksSummary?: string;
+        readonly assigneesCsv?: string;
+    };
+}
+export interface RehydrateData {
+    readonly issueNumber: number;
+    /** Stripped of control chars (operator-editable title — ANSI defense). */
+    readonly title: string;
+    /** Value only — render adds the `state: ` prefix and indentation.
+     * One of:
+     *   "open (unassigned — on the stack)"
+     *   "open (assigned X[,Y...])"
+     *   "closed (accepted YYYY-MM-DD)"
+     *   "closed"
+     */
+    readonly stateLine: string;
+    readonly linkedItems: readonly LinkedItemDerivation[];
+    /** Count of items with state === "UNREACHABLE" (strict-mode trigger). */
+    readonly linkFailures: number;
+    /** Last marker block from `view.body`, INCLUDING the marker tokens.
+     * `null` if no well-formed block found. Control chars NOT yet stripped —
+     * the renderer strips them at print time (matches bash). */
+    readonly note: string | null;
+}
+/**
+ * Derive structured live state for handoff issue #N. Used by /accept (strict),
+ * /rehydrate (lenient), and df_rehydrate (MCP structuredContent).
+ *
+ * Linked items are processed SEQUENTIALLY (bash parity + FakeGhClient ordinal
+ * slot stability). The MAIN issue is the FIRST `issueView` call; any linked
+ * issues that follow share that counter, so test slots are 1 = handoff, 2+ =
+ * linked issues.
+ *
+ * @throws HandoffError if `gh.issueView(issueNum)` fails — the live-state
+ *   anchor is required; don't proceed on the note alone.
+ */
+export declare function deriveRehydrateData(issueNum: number, gh: GhClient): Promise<RehydrateData>;
+//# sourceMappingURL=rehydrate-core.d.ts.map

package/dist/handoff/rehydrate-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rehydrate-core.d.ts","sourceRoot":"","sources":["../../src/handoff/rehydrate-core.ts"],"names":[],"mappings":"AAkCA,OAAO,EAAgB,KAAK,QAAQ,EAAe,MAAM,YAAY,CAAC;AAGtE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,GAAG,GAAG,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,aAAa,CAAC;IAC7D;;gEAE4D;IAC5D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wFAAwF;IACxF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;8EAC0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE;QACf,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;QACnC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;QACjC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAChC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;KAChC,CAAC;CACH;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACtD,yEAAyE;IACzE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;gEAE4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAqJD;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,QAAQ,GACX,OAAO,CAAC,aAAa,CAAC,CA0DxB"}