@gr8ful/spf 0.4.0 → 0.5.1

package/dist/test/signoff.test.js

@@ -0,0 +1,329 @@
+import "./hermetic_git.js";
+/**
+ * Review-accountability thread: an AI reviewer's `approved` flag is a
+ * PROPOSAL; `decideSignoff` (chains/simple_sdlc.ts) is where a human DISPOSES
+ * of it. These tests drive that function directly — running the whole
+ * imperative `simple-sdlc` chain (real agents, a real config, a real
+ * session) is far too heavy just to exercise one decision — plus the
+ * lighter-weight pieces it depends on: `commitEnvelope`'s trailer handling
+ * (chains/steps.ts) and `committerIdentity` (core/git_helper.ts).
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { AI_ONLY_SIGNOFF_WARNING, decideSignoff, trailerFor } from "../chains/simple_sdlc.js";
+import { commitEnvelope } from "../chains/steps.js";
+import { committerIdentity } from "../core/git_helper.js";
+/** A minimal, schema-shaped ReviewOutputT — only the fields decideSignoff reads. */
+function reviewOutput(overrides = {}) {
+    return {
+        status: "success",
+        summary: "",
+        artifacts: [],
+        notes_for_next_agent: "",
+        approved: false,
+        findings: [],
+        blocking: [],
+        ...overrides,
+    };
+}
+/** Records every `confirm()` call — label, the default it was offered, and any timeout — then answers `answer` every time. */
+function scriptedAsker(answer) {
+    const calls = [];
+    const asker = {
+        async text(_label, opts) {
+            return opts?.default ?? "";
+        },
+        async select(_label, _choices, dflt) {
+            return dflt;
+        },
+        async confirm(label, dflt, opts) {
+            calls.push({ label, dflt, timeoutMs: opts?.timeoutMs });
+            return answer;
+        },
+        async secret() {
+            return "";
+        },
+        note() { },
+        heading() { },
+        close() { },
+    };
+    return { asker, calls };
+}
+// ── decideSignoff ────────────────────────────────────────────────────────
+test("decideSignoff: human yes -> accepted, recordedYes true, decision logged against the findings", async () => {
+    const { asker, calls } = scriptedAsker(true);
+    const logs = [];
+    const outcome = await decideSignoff({
+        review: reviewOutput({ approved: true, blocking: [], findings: [{ requirement: "does X", met: true, evidence: "src/x.ts" }] }),
+        canPrompt: true,
+        requireHumanSignoff: false,
+        signoffTimeoutSeconds: 300,
+        asker,
+        identity: { name: "Ada Lovelace", email: "ada@example.com" },
+        log: (p) => logs.push(p),
+        warn: () => { },
+    });
+    assert.equal(outcome.accepted, true);
+    assert.equal(outcome.recordedYes, true);
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0].dflt, false, "the prompt's own default must be false, never review.approved (no auto-approval bias)");
+    assert.equal(calls[0].timeoutMs, 300_000, "signoffTimeoutSeconds must reach confirm() as milliseconds");
+    assert.ok(logs.some((l) => l.decision === "approved" && l.human === true && Array.isArray(l.findings)), "the decision, engineer identity, and findings basis must land in the trace via ph.log");
+});
+test("decideSignoff: human no -> not accepted, never a recorded yes", async () => {
+    const { asker } = scriptedAsker(false);
+    const logs = [];
+    const outcome = await decideSignoff({
+        review: reviewOutput({ approved: true, blocking: ["still missing a test"] }),
+        canPrompt: true,
+        requireHumanSignoff: false,
+        signoffTimeoutSeconds: 300,
+        asker,
+        identity: { name: "Ada Lovelace", email: "ada@example.com" },
+        log: (p) => logs.push(p),
+        warn: () => { },
+    });
+    assert.equal(outcome.accepted, false);
+    assert.equal(outcome.recordedYes, false);
+    assert.ok(logs.some((l) => l.decision === "declined"));
+});
+test("decideSignoff: an expired prompt resolves to confirm()'s own default (false) -> not accepted, not a recorded yes", async () => {
+    // cli/ask.ts's real confirm() collapses an expired timer into `dflt` — a
+    // fake whose confirm mimics that exact collapse is the faithful stand-in
+    // for "the timeout fired" without actually waiting out a real clock here.
+    const asker = {
+        async text(_l, opts) {
+            return opts?.default ?? "";
+        },
+        async select(_l, _c, dflt) {
+            return dflt;
+        },
+        async confirm(_label, dflt) {
+            return dflt;
+        },
+        async secret() {
+            return "";
+        },
+        note() { },
+        heading() { },
+        close() { },
+    };
+    const outcome = await decideSignoff({
+        review: reviewOutput({ approved: true }),
+        canPrompt: true,
+        requireHumanSignoff: false,
+        signoffTimeoutSeconds: 1,
+        asker,
+        identity: undefined,
+        log: () => { },
+        warn: () => { },
+    });
+    assert.equal(outcome.accepted, false);
+    assert.equal(outcome.recordedYes, false);
+});
+test("decideSignoff: unattended, require_human_signoff false -> proceeds on the AI verdict alone, with a loud warning printed and logged", async () => {
+    const warns = [];
+    const logs = [];
+    const outcome = await decideSignoff({
+        review: reviewOutput({ approved: true }),
+        canPrompt: false,
+        requireHumanSignoff: false,
+        signoffTimeoutSeconds: 300,
+        asker: null,
+        identity: undefined,
+        log: (p) => logs.push(p),
+        warn: (l) => warns.push(l),
+    });
+    assert.equal(outcome.accepted, true, "review.approved alone gates the commit on this default-false, unattended path");
+    assert.equal(outcome.recordedYes, false, "never a recorded human yes when nobody was asked");
+    assert.ok(warns.some((w) => w.includes(AI_ONLY_SIGNOFF_WARNING)), "the warning must be loud (printed), not just traced");
+    assert.ok(logs.some((l) => l.decision === "ai_only" && l.warning === AI_ONLY_SIGNOFF_WARNING), "the warning text itself must also land in the traced payload, not just stdout");
+});
+test("decideSignoff: unattended, require_human_signoff true -> fails the phase closed instead of auto-approving", async () => {
+    await assert.rejects(() => decideSignoff({
+        review: reviewOutput({ approved: true }),
+        canPrompt: false,
+        requireHumanSignoff: true,
+        signoffTimeoutSeconds: 300,
+        asker: null,
+        identity: undefined,
+        log: () => { },
+        warn: () => { },
+    }), /unattended/);
+});
+test("decideSignoff: no TTY behaves the same as unattended, even if ctx.unattended alone said otherwise — canPrompt is the conjunction", async () => {
+    // This is `isInteractive() && !ctx.unattended` already folded down to a
+    // single boolean by the caller (simple_sdlc.ts) — decideSignoff itself
+    // just trusts `canPrompt`, so this pins that "false" here means the
+    // AI-only/fail-closed branch regardless of which half made it false.
+    await assert.rejects(() => decideSignoff({
+        review: reviewOutput({ approved: true }),
+        canPrompt: false,
+        requireHumanSignoff: true,
+        signoffTimeoutSeconds: 300,
+        asker: null,
+        identity: undefined,
+        log: () => { },
+        warn: () => { },
+    }), /unattended/);
+});
+test("decideSignoff: no git committer identity -> the decision is still logged; the trailer is the caller's problem to skip", async () => {
+    const { asker } = scriptedAsker(true);
+    const logs = [];
+    const warns = [];
+    const outcome = await decideSignoff({
+        review: reviewOutput({ approved: true }),
+        canPrompt: true,
+        requireHumanSignoff: false,
+        signoffTimeoutSeconds: 300,
+        asker,
+        identity: undefined,
+        log: (p) => logs.push(p),
+        warn: (l) => warns.push(l),
+    });
+    assert.equal(outcome.recordedYes, true, "the human said yes — a missing identity affects the trailer, never the decision itself");
+    assert.ok(logs.some((l) => typeof l.note === "string" && l.note.includes("without a git committer identity")));
+});
+// ── trailerFor: the join between decideSignoff and commitEnvelope ────────
+test("trailerFor: the AI-only path's recordedYes:false reaches commitEnvelope as null, even when accepted is true and an identity exists", () => {
+    // The exact join this test guards: a refactor that swapped `recordedYes`
+    // for `accepted` (or `verified`) at the commit_build call site would keep
+    // every other test in this suite green while minting trailers for
+    // AI-only commits.
+    const identity = { name: "Ada Lovelace", email: "ada@example.com" };
+    assert.equal(trailerFor({ accepted: true, recordedYes: false }, identity), null);
+});
+test("trailerFor: a recorded human yes with an identity reaches commitEnvelope as that identity", () => {
+    const identity = { name: "Ada Lovelace", email: "ada@example.com" };
+    assert.deepEqual(trailerFor({ accepted: true, recordedYes: true }, identity), identity);
+});
+test("trailerFor: a recorded human yes with no git identity configured still yields null, not a fabricated one", () => {
+    assert.equal(trailerFor({ accepted: true, recordedYes: true }, undefined), null);
+});
+// ── commitEnvelope's trailer ─────────────────────────────────────────────
+function fakeCommitRun() {
+    const committed = [];
+    const run = {
+        adw_id: "abcd1234",
+        git: {
+            commitAll: (message) => {
+                committed.push(message);
+                return "abc1234";
+            },
+        },
+    };
+    return { run, committed };
+}
+function fakePh() {
+    return {
+        log: () => { },
+        call: async () => {
+            throw new Error("not used by these tests");
+        },
+    };
+}
+test("commitEnvelope: a recorded human sign-off appends a real Signed-off-by trailer", () => {
+    const { run, committed } = fakeCommitRun();
+    commitEnvelope(run, fakePh(), { status: "success", summary: "did it", artifacts: [], notes_for_next_agent: "", commit_message: "Implement the thing" }, { name: "Ada Lovelace", email: "ada@example.com" });
+    assert.equal(committed.length, 1);
+    assert.equal(committed[0], "Implement the thing\n\nSigned-off-by: Ada Lovelace <ada@example.com>");
+});
+test("commitEnvelope: no signoff argument -> no trailer, ever", () => {
+    const { run, committed } = fakeCommitRun();
+    commitEnvelope(run, fakePh(), {
+        status: "success",
+        summary: "did it",
+        artifacts: [],
+        notes_for_next_agent: "",
+        commit_message: "Implement the thing",
+    });
+    assert.equal(committed[0], "Implement the thing");
+    assert.doesNotMatch(committed[0], /Signed-off-by/);
+});
+test("commitEnvelope: an explicit null signoff (identity was unset) -> no trailer, same as omitted", () => {
+    const { run, committed } = fakeCommitRun();
+    commitEnvelope(run, fakePh(), { status: "success", summary: "did it", artifacts: [], notes_for_next_agent: "", commit_message: "Fixed it" }, null);
+    assert.doesNotMatch(committed[0], /Signed-off-by/);
+});
+test("commitEnvelope: a lone conventional-commit subject is never mistaken for a trailer block", () => {
+    // Regression: `feat: add X` matches TRAILER_LINE's `Key: value` shape, but
+    // a single paragraph is the SUBJECT, never an existing trailer block — the
+    // trailer must land after a blank line, not glued onto the subject with no
+    // separator (which git would not recognize as a trailer at all).
+    const { run, committed } = fakeCommitRun();
+    commitEnvelope(run, fakePh(), { status: "success", summary: "did it", artifacts: [], notes_for_next_agent: "", commit_message: "feat: add the signoff gate" }, { name: "Ada Lovelace", email: "ada@example.com" });
+    assert.equal(committed[0], "feat: add the signoff gate\n\nSigned-off-by: Ada Lovelace <ada@example.com>");
+});
+test("commitEnvelope: a real body ending in a Key: value block still joins rather than growing a blank-line-separated second block", () => {
+    const { run, committed } = fakeCommitRun();
+    commitEnvelope(run, fakePh(), { status: "success", summary: "", artifacts: [], notes_for_next_agent: "", commit_message: "wip\n\nNote: I did stuff" }, { name: "Ada Lovelace", email: "ada@example.com" });
+    assert.equal(committed[0], "wip\n\nNote: I did stuff\nSigned-off-by: Ada Lovelace <ada@example.com>");
+});
+test("commitEnvelope: an agent-authored message that already carries this exact Signed-off-by line is not duplicated", () => {
+    const { run, committed } = fakeCommitRun();
+    commitEnvelope(run, fakePh(), {
+        status: "success",
+        summary: "",
+        artifacts: [],
+        notes_for_next_agent: "",
+        commit_message: "feat: add the signoff gate\n\nSigned-off-by: Ada Lovelace <ada@example.com>",
+    }, { name: "Ada Lovelace", email: "ada@example.com" });
+    assert.equal(committed[0], "feat: add the signoff gate\n\nSigned-off-by: Ada Lovelace <ada@example.com>");
+    assert.equal(committed[0].match(/Signed-off-by/g)?.length, 1);
+});
+test("commitEnvelope: joins an already-trailered message's block instead of starting a second one", () => {
+    const { run, committed } = fakeCommitRun();
+    commitEnvelope(run, fakePh(), {
+        status: "success",
+        summary: "",
+        artifacts: [],
+        notes_for_next_agent: "",
+        commit_message: "Implement the thing\n\nCo-authored-by: Bot <bot@example.com>",
+    }, { name: "Ada Lovelace", email: "ada@example.com" });
+    assert.equal(committed[0], "Implement the thing\n\nCo-authored-by: Bot <bot@example.com>\nSigned-off-by: Ada Lovelace <ada@example.com>");
+});
+// ── committerIdentity ────────────────────────────────────────────────────
+test("committerIdentity: reads the repo-local user.name/user.email", () => {
+    const dir = mkdtempSync(path.join(tmpdir(), "spf-signoff-identity-"));
+    try {
+        execFileSync("git", ["init"], { cwd: dir, stdio: "ignore" });
+        execFileSync("git", ["config", "user.name", "Ada Lovelace"], { cwd: dir, stdio: "ignore" });
+        execFileSync("git", ["config", "user.email", "ada@example.com"], { cwd: dir, stdio: "ignore" });
+        assert.deepEqual(committerIdentity(dir), { name: "Ada Lovelace", email: "ada@example.com" });
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("committerIdentity: undefined (never a fallback literal) when no config carries a name/email", () => {
+    const dir = mkdtempSync(path.join(tmpdir(), "spf-signoff-identity-unset-"));
+    const fakeHome = mkdtempSync(path.join(tmpdir(), "spf-signoff-fakehome-"));
+    const saved = {
+        HOME: process.env.HOME,
+        GIT_CONFIG_GLOBAL: process.env.GIT_CONFIG_GLOBAL,
+        GIT_CONFIG_NOSYSTEM: process.env.GIT_CONFIG_NOSYSTEM,
+    };
+    try {
+        execFileSync("git", ["init"], { cwd: dir, stdio: "ignore" });
+        // Isolate from whatever global/system gitconfig the host running this
+        // suite happens to have — otherwise "unset" is only true by accident.
+        process.env.HOME = fakeHome;
+        process.env.GIT_CONFIG_GLOBAL = path.join(fakeHome, "does-not-exist");
+        process.env.GIT_CONFIG_NOSYSTEM = "1";
+        assert.equal(committerIdentity(dir), undefined);
+    }
+    finally {
+        for (const [key, value] of Object.entries(saved)) {
+            if (value === undefined)
+                delete process.env[key];
+            else
+                process.env[key] = value;
+        }
+        rmSync(dir, { recursive: true, force: true });
+        rmSync(fakeHome, { recursive: true, force: true });
+    }
+});

package/dist/test/ui_server.test.d.ts

@@ -1 +1,7 @@
-export {};
+/**
+ * Route-parity regression test for the Bun.serve -> Hono port. Builds a real
+ * spf.db (via the tracer, not a fixture file) and drives runUi() with real
+ * HTTP requests — the same shape as the manual verification this port was
+ * checked against, kept as a regression guard rather than a one-off.
+ */
+import "./hermetic_git.js";

package/dist/test/ui_server.test.js

@@ -4,6 +4,7 @@
  * HTTP requests — the same shape as the manual verification this port was
  * checked against, kept as a regression guard rather than a one-off.
  */
+import "./hermetic_git.js";
 import { test, before, after } from "node:test";
 import assert from "node:assert/strict";
 import { mkdtempSync, rmSync } from "node:fs";

package/dist/test/watch.test.js

@@ -2,6 +2,20 @@ import { test } from "node:test";
 import assert from "node:assert/strict";
 import path from "node:path";
 import { branchNameFor, claimNewWork, claimSpecs, createWatchState, finishReviews, reconcileOrphans, reconcileRefining, refineBranchNameFor, tick, } from "../core/watch.js";
+import { escapeForMarkup, formatReviewDigest, truncateDigest } from "../cli/commands/watch.js";
+/** A minimal, schema-shaped ReviewOutputT — only the fields formatReviewDigest reads. */
+function reviewOutput(overrides = {}) {
+    return {
+        status: "success",
+        summary: "",
+        artifacts: [],
+        notes_for_next_agent: "",
+        approved: false,
+        findings: [],
+        blocking: [],
+        ...overrides,
+    };
+}
 /** In-memory fake — exactly the seam `provider.ts` exists for. */
 class FakeProvider {
     entries = new Map();
@@ -50,7 +64,7 @@ class FakeCodeHost {
     nextPrNumber = 1000;
     async openPr(opts) {
         const number = this.nextPrNumber++;
-        this.openedPrs.push({ title: opts.title, branch: opts.branch });
+        this.openedPrs.push({ title: opts.title, branch: opts.branch, body: opts.body });
         this.prs.set(number, { merged: false, state: "open", ciStatus: "pending" });
         return { number, branch: opts.branch, url: `https://example.invalid/pr/${number}` };
     }
@@ -390,6 +404,61 @@ test("reconcileOrphans: a routine orphan resume/retry notifies nothing — only
     await reconcileOrphans(makeDeps(provider, codeHost, { notify }), state);
     assert.deepEqual(events, []);
 });
+// ── the review digest threaded into the PR + pr_opened notification ────────
+test("claimNewWork: a reviewSummary from runChain lands in the PR body and the pr_opened event's detail/fields", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("60", "Add a /health endpoint");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    const deps = makeDeps(provider, codeHost, {
+        notify,
+        runChain: async (opts) => ({
+            accepted: true,
+            adwId: opts.adwId,
+            detail: "",
+            reviewRequired: true,
+            reviewSummary: "Reviewer verdict: changes requested.\nBlocking:\n- add a test",
+        }),
+    });
+    await claimNewWork(deps, state);
+    await waitUntil(() => state.inflight.size === 0);
+    assert.match(codeHost.openedPrs[0].body, /Automated by `spf watch`/);
+    assert.match(codeHost.openedPrs[0].body, /Reviewer verdict: changes requested\.\nBlocking:\n- add a test/);
+    const prOpened = events.find((e) => e.kind === "pr_opened");
+    assert.equal(prOpened.detail, "Reviewer verdict: changes requested.\nBlocking:\n- add a test");
+    assert.deepEqual(prOpened.fields.find(([k]) => k === "review"), ["review", "reviewed"]);
+});
+test("claimNewWork: a reviewer-required chain with no readable verdict says so, distinctly from no reviewer at all", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("61", "Add a /health endpoint");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    const deps = makeDeps(provider, codeHost, {
+        notify,
+        runChain: async (opts) => ({ accepted: true, adwId: opts.adwId, detail: "", reviewRequired: true }),
+    });
+    await claimNewWork(deps, state);
+    await waitUntil(() => state.inflight.size === 0);
+    assert.match(codeHost.openedPrs[0].body, /no verdict could be read back/);
+    const prOpened = events.find((e) => e.kind === "pr_opened");
+    assert.deepEqual(prOpened.fields.find(([k]) => k === "review"), ["review", "reviewer ran, no verdict"]);
+});
+test("claimNewWork: a chain with no reviewer step says nothing reviewed this change", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("62", "Add a /health endpoint");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    // makeDeps' default runChain returns neither reviewRequired nor reviewSummary.
+    const deps = makeDeps(provider, codeHost, { notify });
+    await claimNewWork(deps, state);
+    await waitUntil(() => state.inflight.size === 0);
+    assert.match(codeHost.openedPrs[0].body, /Nothing reviewed this change — chain `plan-build-test` has no reviewer step\./);
+    const prOpened = events.find((e) => e.kind === "pr_opened");
+    assert.deepEqual(prOpened.fields.find(([k]) => k === "review"), ["review", "not reviewed"]);
+});
 // ── the refine lane ──────────────────────────────────────────────────────
 test("refineBranchNameFor: same sanitizer as branchNameFor, different prefix", () => {
     assert.equal(refineBranchNameFor({ id: "9", title: "Team invitations spec", body: "", labels: [] }), "spf-refine/9-team-invitations-spec");
@@ -550,6 +619,60 @@ test("claim -> refine -> published fires issue_claimed then spec_refined, both i
     assert.deepEqual(events.map((e) => e.kind), ["issue_claimed", "spec_refined"]);
     assert.ok(events.every((e) => e.level === "info"));
 });
+// ── escapeForMarkup / truncateDigest / formatReviewDigest ───────────────────
+// These three are what actually assembles the digest — the tests above only
+// exercise core/watch.ts's three-way reviewLine selection via a stubbed
+// runChain, so none of them ever call into these. Slack/GitHub markup
+// escaping is the one security-relevant behavior spec item B calls out by
+// name (a reviewer's findings are LLM-authored, hence untrusted), so it needs
+// direct coverage.
+test("escapeForMarkup: a Slack link-forgery attempt is neutralized, and & is escaped without double-escaping", () => {
+    const escaped = escapeForMarkup("<https://evil.example/|click here> & enjoy");
+    assert.equal(escaped, "&lt;https://evil.example/|click here&gt; &amp; enjoy");
+    assert.ok(!escaped.includes("<") && !escaped.includes(">"), "no raw angle bracket must survive — that's what prevents a forged Slack mrkdwn link");
+});
+test("formatReviewDigest: an approved review's met findings are the actual signal, and are surfaced (not silently dropped)", () => {
+    const review = reviewOutput({
+        approved: true,
+        findings: [
+            { requirement: "endpoint returns 200", met: true, evidence: "curl output attached" },
+            { requirement: "handles missing auth header", met: true, evidence: "" },
+            { requirement: "logs the request id", met: true, evidence: "trace shows request_id field" },
+        ],
+        blocking: [],
+    });
+    const digest = formatReviewDigest(review);
+    assert.match(digest, /^Reviewer verdict: approved\./);
+    assert.match(digest, /Verified 3 requirement\(s\):/);
+    assert.match(digest, /- endpoint returns 200 — curl output attached/);
+    assert.match(digest, /- handles missing auth header/);
+    assert.match(digest, /- logs the request id — trace shows request_id field/);
+});
+test("formatReviewDigest: blocking items and unmet findings are escaped before being joined in", () => {
+    const review = reviewOutput({
+        approved: false,
+        blocking: ["contains a <https://evil.example/|forged link> & needs fixing"],
+        findings: [{ requirement: "auth check <script>", met: false, evidence: "not implemented & untested" }],
+    });
+    const digest = formatReviewDigest(review);
+    assert.match(digest, /^Reviewer verdict: changes requested\./);
+    assert.match(digest, /- contains a &lt;https:\/\/evil\.example\/\|forged link&gt; &amp; needs fixing/);
+    assert.match(digest, /- auth check &lt;script&gt; — not implemented &amp; untested/);
+    assert.ok(!digest.includes("<script>") && !digest.includes("<https"), "raw markup from an unmet finding must not survive into the digest");
+});
+test("truncateDigest: a digest over the cap is cut at exactly the codepoint boundary, without splitting a surrogate pair", () => {
+    // An astral-plane emoji (2 UTF-16 code units, 1 codepoint) placed exactly
+    // at the 1200th codepoint — a naive `.slice(0, 1200)` on UTF-16 units would
+    // land mid-pair and emit a lone, invalid surrogate instead of the emoji.
+    const emoji = "\u{1F600}"; // grinning face, codepoint #1200
+    const filler = "a".repeat(1199); // codepoints #1-1199
+    const text = filler + emoji + "more text that must be cut off entirely";
+    const result = truncateDigest(text);
+    assert.equal(result, filler + emoji + "…", "must keep exactly 1200 whole codepoints (the emoji intact) then the ellipsis");
+    assert.ok(result.endsWith("…"), "a truncated digest must end with the ellipsis marker");
+    const short = "short digest, well under the cap";
+    assert.equal(truncateDigest(short), short, "text under the cap must pass through unchanged, with no ellipsis appended");
+});
 test("tick: a per-stage error is caught and fires exactly one watch_error", async () => {
     const provider = new FakeProvider();
     const codeHost = new FakeCodeHost();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gr8ful/spf",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Super Portable Factory — a global CLI for repeatable agents-plus-code workflows (ADWs)",
   "type": "module",
   "license": "MIT",
@@ -18,10 +18,6 @@
     "README.md",
     "LICENSE"
   ],
-  "exports": {
-    ".": "./dist/index.js",
-    "./core": "./dist/core/index.js"
-  },
   "engines": {
     "node": ">=22.19.0"
   },
@@ -44,6 +40,7 @@
     "tag:patch": "node scripts/tag-release.js patch"
   },
   "dependencies": {
+    "@earendil-works/pi-ai": "0.83.0",
     "@flue/runtime": "2.0.3",
     "@hono/node-server": "^2.1.1",
     "@valibot/to-json-schema": "^1.7.1",
@@ -51,6 +48,9 @@
     "valibot": "^1.4.2",
     "yaml": "^2.5.1"
   },
+  "overrides": {
+    "@earendil-works/pi-ai": "0.83.0"
+  },
   "devDependencies": {
     "@types/node": "^22.10.0",
     "lefthook": "^2.1.10",