@jitsusama/agentic-harness.core 0.1.0

package/dist/internal/guardian/commit-shell.js

@@ -0,0 +1,134 @@
+/**
+ * Git commit command parsing: locating a git commit past its
+ * global options and extracting its message (heredoc, -m/-am, or
+ * -F file) on the command model.
+ *
+ * These are commit-guardian internals. General-purpose shell
+ * parsing lives in lib/shell/.
+ */
+import { effectiveCwd, findFlag, findFlags, tokenize, } from "../../command/index.js";
+import { unquote } from "../../shell/index.js";
+/**
+ * Git global options that sit before the subcommand and take a
+ * separate value, so the value token is skipped when locating the
+ * subcommand. Attached forms (-Cpath, --git-dir=...) and the
+ * boolean globals consume only their own token.
+ */
+const GIT_GLOBAL_VALUE_FLAGS = new Set([
+    "-C",
+    "-c",
+    "--git-dir",
+    "--work-tree",
+    "--namespace",
+    "--config-env",
+    "--super-prefix",
+]);
+/**
+ * Index of the git subcommand in argv, skipping any leading global
+ * options, or -1 when this is not a git command or has no
+ * subcommand. So `git -C dir commit` resolves to the index of
+ * `commit`, not `-C`.
+ */
+function gitSubcommandIndex(argv) {
+    if (argv[0]?.text !== "git")
+        return -1;
+    let i = 1;
+    while (i < argv.length) {
+        const token = argv[i].text;
+        if (!token.startsWith("-"))
+            return i;
+        i += GIT_GLOBAL_VALUE_FLAGS.has(token) ? 2 : 1;
+    }
+    return -1;
+}
+/**
+ * Find the git command in a tokenized line whose subcommand is
+ * `sub`, looking past leading global options so a form like
+ * `git -C dir commit` is still found.
+ */
+export function findGitCommand(line, sub) {
+    return line.commands.find((command) => {
+        const index = gitSubcommandIndex(command.argv);
+        return index >= 0 && command.argv[index]?.text === sub;
+    });
+}
+/** Whether a bash command contains a git commit, global options aside. */
+export function isGitCommitCommand(command) {
+    return findGitCommand(tokenize(command), "commit") !== undefined;
+}
+/**
+ * The commit flags that carry a message or affect how a clustered
+ * short flag like `-am` is read. The message and file flags carry
+ * a value; the rest are the common boolean shorts that can precede
+ * `-m` in a cluster, so the cluster parses safely.
+ */
+const COMMIT_MESSAGE_SPEC = {
+    flags: [
+        { name: "message", long: "message", short: "m", takesValue: true },
+        { name: "file", long: "file", short: "F", takesValue: true },
+        { name: "all", long: "all", short: "a", takesValue: false },
+        { name: "signoff", long: "signoff", short: "s", takesValue: false },
+        { name: "verbose", long: "verbose", short: "v", takesValue: false },
+        { name: "quiet", long: "quiet", short: "q", takesValue: false },
+        { name: "edit", long: "edit", short: "e", takesValue: false },
+    ],
+};
+/**
+ * Extract the commit message from a bash command.
+ *
+ * Supports the heredoc form (git commit -F- <<'EOF'...EOF), one or
+ * more -m/--message flags (including the -am cluster), and a
+ * -F <file> read through the optional reader.
+ *
+ * Parsing runs on the command model, so only the git commit
+ * command's own argv and heredoc are read. A -m written inside a
+ * heredoc body, or a heredoc belonging to a chained command, is
+ * never mistaken for the message, because neither lives in the
+ * commit's argv.
+ *
+ * A `git commit -F <file>` (a real file, not `-F-` stdin) is
+ * resolved through the optional `readFile` reader, which is given
+ * the raw path and the command's effective working directory and
+ * returns the file's contents or null. Without a reader, or when
+ * the read fails, this returns null and the caller no-ops, so an
+ * unreadable file is a missed gate, never a wrong rewrite.
+ */
+export function extractMessage(command, readFile) {
+    const line = tokenize(command);
+    const commit = findGitCommand(line, "commit");
+    if (!commit)
+        return null;
+    if (commit.heredoc) {
+        return command.slice(commit.heredoc.bodySpan.start, commit.heredoc.bodySpan.end);
+    }
+    const messages = findFlags(commit, COMMIT_MESSAGE_SPEC, "message").map((m) => m.value === undefined ? "" : unquote(m.value));
+    if (messages.length > 0)
+        return messages.join("\n\n");
+    return readFileMessage(line, commit, readFile);
+}
+/**
+ * Resolve a `git commit -F <file>` message through the reader.
+ * Returns null when there is no file flag, when the path is `-`
+ * (stdin, handled elsewhere), when no reader is supplied, or when
+ * the read fails.
+ */
+function readFileMessage(line, commit, readFile) {
+    if (!readFile)
+        return null;
+    const flag = findFlag(commit, COMMIT_MESSAGE_SPEC, "file");
+    if (!flag || flag.value === undefined)
+        return null;
+    const rawPath = unquote(flag.value);
+    if (rawPath === "-")
+        return null;
+    // Resolve the relative path against the command's effective
+    // working directory (the pi cwd composed with any leading cd
+    // segments). An unresolvable cd chain falls back to the process
+    // cwd reader-side.
+    const cwd = effectiveCwd(line, process.cwd(), commit.span.start);
+    const baseDir = "dir" in cwd ? cwd.dir : null;
+    const contents = readFile(rawPath, baseDir);
+    if (contents === null)
+        return null;
+    return contents.replace(/\n+$/, "");
+}

package/dist/internal/guardian/history-gate.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Destructive git command detection: the decision core behind
+ * history-guardian's confirmation gate.
+ *
+ * Unlike the content gates (prose, section, title), this has no
+ * block-once-relent-on-repeat state machine: a `git reset --hard`
+ * is exactly as destructive the fifth time it is attempted as the
+ * first, so there is nothing here for a GateDeps signature store to
+ * do. Detection runs fresh on every command.
+ *
+ * Getting a human's actual allow/block/redirect decision needs a
+ * host's own confirmation UI (pi's modal, Claude Code's native
+ * permission prompt) and stays adapter-local, along with how each
+ * host renders the match into what its UI shows. This is only the
+ * pure "is this command one of the ones we warn about" question.
+ */
+/** How dangerous a destructive git operation is. */
+export type Severity = "irrecoverable" | "risky";
+/** A regex pattern that matches a destructive git command. */
+export interface DestructivePattern {
+    pattern: RegExp;
+    severity: Severity;
+    description: string;
+}
+/**
+ * Known destructive git patterns, ordered from most specific to
+ * most general so narrower matches win (e.g. --force-with-lease,
+ * risky, must precede the general --force pattern, irrecoverable).
+ */
+export declare const DESTRUCTIVE_PATTERNS: DestructivePattern[];
+/** A command matched against the destructive patterns. */
+export interface DestructiveMatch {
+    command: string;
+    severity: Severity;
+    description: string;
+}
+/**
+ * Match a command against the known destructive patterns, returning
+ * the first (most specific) match, or null when nothing matches.
+ */
+export declare function detectDestructiveCommand(command: string): DestructiveMatch | null;

package/dist/internal/guardian/history-gate.js

@@ -0,0 +1,76 @@
+/**
+ * Destructive git command detection: the decision core behind
+ * history-guardian's confirmation gate.
+ *
+ * Unlike the content gates (prose, section, title), this has no
+ * block-once-relent-on-repeat state machine: a `git reset --hard`
+ * is exactly as destructive the fifth time it is attempted as the
+ * first, so there is nothing here for a GateDeps signature store to
+ * do. Detection runs fresh on every command.
+ *
+ * Getting a human's actual allow/block/redirect decision needs a
+ * host's own confirmation UI (pi's modal, Claude Code's native
+ * permission prompt) and stays adapter-local, along with how each
+ * host renders the match into what its UI shows. This is only the
+ * pure "is this command one of the ones we warn about" question.
+ */
+/**
+ * Known destructive git patterns, ordered from most specific to
+ * most general so narrower matches win (e.g. --force-with-lease,
+ * risky, must precede the general --force pattern, irrecoverable).
+ */
+export const DESTRUCTIVE_PATTERNS = [
+    // Risky: recoverable via reflog or other means
+    {
+        pattern: /\bgit\s+push\b[^|;]*--force-with-lease\b/,
+        severity: "risky",
+        description: "Force push with lease: safer than --force but still rewrites remote history.",
+    },
+    {
+        pattern: /\bgit\s+stash\s+drop\b/,
+        severity: "risky",
+        description: "Drops a stash entry. Recoverable via git reflog for ~30 days.",
+    },
+    {
+        pattern: /\bgit\s+rebase\b/,
+        severity: "risky",
+        description: "Rewrites commit history. Recoverable via git reflog.",
+    },
+    // Irrecoverable: data loss likely
+    {
+        pattern: /\bgit\s+reset\s+--hard\b/,
+        severity: "irrecoverable",
+        description: "Permanently discards all uncommitted changes.",
+    },
+    {
+        pattern: /\bgit\s+clean\s+-[a-z]*f/,
+        severity: "irrecoverable",
+        description: "Permanently deletes untracked files.",
+    },
+    {
+        pattern: /\bgit\s+push\b[^|;]*(?:--force\b|-f\b)/,
+        severity: "irrecoverable",
+        description: "Force push overwrites remote history: commits may be permanently lost.",
+    },
+    {
+        pattern: /\bgit\s+branch\s+-D\b/,
+        severity: "irrecoverable",
+        description: "Force-deletes branch regardless of merge status.",
+    },
+    {
+        pattern: /\bgit\s+checkout\s+--\s+\./,
+        severity: "irrecoverable",
+        description: "Discards all uncommitted changes to tracked files.",
+    },
+];
+/**
+ * Match a command against the known destructive patterns, returning
+ * the first (most specific) match, or null when nothing matches.
+ */
+export function detectDestructiveCommand(command) {
+    for (const { pattern, severity, description } of DESTRUCTIVE_PATTERNS) {
+        if (pattern.test(command))
+            return { command, severity, description };
+    }
+    return null;
+}

package/dist/internal/guardian/prose-gate.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Guardian-side glue for the prose gate. Detects prose
+ * violations in a body, asks the pure decision what to do, and
+ * persists a new signature when it blocks. The decision logic
+ * lives in the prose and gate modules; this is only the
+ * read/persist wiring against a caller-supplied signature store.
+ *
+ * The signature store itself (`GateDeps`) is deliberately not
+ * implemented here: reading and persisting a "have I blocked this
+ * before" signature means something different per adapter (pi
+ * keeps it in its session log; a stateless CLI would keep it in
+ * its own state file). Each adapter supplies its own `GateDeps`.
+ */
+import type { GateDeps } from "../../gate/index.js";
+import type { GuardianResult } from "../../guardian/types.js";
+export type { GateDeps };
+/** Run the prose gate over a body. Returns a block or undefined. */
+export declare function runProseGate(deps: GateDeps, body: string | null): GuardianResult;
+/**
+ * The relent message, when the prose gate is letting this exact
+ * body through after already blocking it once, else null.
+ *
+ * A caller that only reads `runProseGate`'s block-or-undefined
+ * result cannot tell "clean" and "relented" apart, since both fall
+ * through to undefined by design (see above). pi's own review UI
+ * doesn't need to tell them apart either, since it renders the body
+ * in full regardless. A caller whose "ask" is a synthesized summary
+ * (a Claude Code hook's permission reason) does need to, so a
+ * relented violation is not silently reported as clean.
+ */
+export declare function proseGateNote(deps: GateDeps, body: string | null): string | null;

package/dist/internal/guardian/prose-gate.js

@@ -0,0 +1,50 @@
+/**
+ * Guardian-side glue for the prose gate. Detects prose
+ * violations in a body, asks the pure decision what to do, and
+ * persists a new signature when it blocks. The decision logic
+ * lives in the prose and gate modules; this is only the
+ * read/persist wiring against a caller-supplied signature store.
+ *
+ * The signature store itself (`GateDeps`) is deliberately not
+ * implemented here: reading and persisting a "have I blocked this
+ * before" signature means something different per adapter (pi
+ * keeps it in its session log; a stateless CLI would keep it in
+ * its own state file). Each adapter supplies its own `GateDeps`.
+ */
+import { detectProseViolations, proseGateDecision } from "../../prose/index.js";
+/** Run the prose gate over a body. Returns a block or undefined. */
+export function runProseGate(deps, body) {
+    if (!body)
+        return undefined;
+    const violations = detectProseViolations(body);
+    const decision = proseGateDecision(violations, deps.readSignatures(), body);
+    if (decision.action === "block") {
+        deps.persistSignature(decision.signature);
+        return { block: true, reason: decision.message };
+    }
+    // On relent the AI already had its chance and could not satisfy
+    // the rule, so blocking again would loop. Fall through to the
+    // normal human review gate (undefined) and let the user be the
+    // safety net; they see the rendered body and can reject it. On
+    // allow we also fall through. Either way we record nothing new.
+    return undefined;
+}
+/**
+ * The relent message, when the prose gate is letting this exact
+ * body through after already blocking it once, else null.
+ *
+ * A caller that only reads `runProseGate`'s block-or-undefined
+ * result cannot tell "clean" and "relented" apart, since both fall
+ * through to undefined by design (see above). pi's own review UI
+ * doesn't need to tell them apart either, since it renders the body
+ * in full regardless. A caller whose "ask" is a synthesized summary
+ * (a Claude Code hook's permission reason) does need to, so a
+ * relented violation is not silently reported as clean.
+ */
+export function proseGateNote(deps, body) {
+    if (!body)
+        return null;
+    const violations = detectProseViolations(body);
+    const decision = proseGateDecision(violations, deps.readSignatures(), body);
+    return decision.action === "relent" ? decision.message : null;
+}

package/dist/internal/guardian/redirect-gate.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Guardian-side glue for sending a shell command to the tool that can
+ * reach the repo it names.
+ *
+ * `gh pr create` is the wrong instrument wherever something other than
+ * GitHub hosts the changes: it reaches a mirror that has never heard of
+ * them, and answers with "Could not resolve to a PullRequest with the
+ * number of ...", which reads as a wrong number rather than as the wrong
+ * system. A skill description helps somebody who wonders whether another
+ * tool exists; this is for the case where nobody wondered.
+ *
+ * Only for creating. A create uses the branch in this checkout, so the
+ * checkout's provider is the right question to ask. An edit names a
+ * change that may live in another repo entirely, `-R` and all, so the
+ * skills cover that in words rather than this guessing at it.
+ *
+ * Blocks once and relents on a repeat, the same machinery the title,
+ * section and prose gates use, so it cannot loop and somebody who means
+ * `gh` still gets it on the second try.
+ */
+import { type GateDeps } from "../../gate/index.js";
+import type { GuardianResult } from "../../guardian/types.js";
+export type { GateDeps };
+/** What the gate needs to know about the command and where it runs. */
+export interface RedirectSubject {
+    /** "create" or "edit"; only a create is redirected. */
+    action: string;
+    /** The directory the command would run in. */
+    cwd: string | undefined;
+    /** How to ask git about the checkout. */
+    exec: ((command: string, args: string[]) => Promise<{
+        code: number;
+        stdout: string;
+        stderr: string;
+    }>) | undefined;
+}
+/**
+ * Redirect a create to the review tools when a provider serves this
+ * checkout. Returns a block, or undefined to let the command through.
+ */
+export declare function runRedirectGate(deps: GateDeps, subject: RedirectSubject): Promise<GuardianResult>;

package/dist/internal/guardian/redirect-gate.js

@@ -0,0 +1,114 @@
+/**
+ * Guardian-side glue for sending a shell command to the tool that can
+ * reach the repo it names.
+ *
+ * `gh pr create` is the wrong instrument wherever something other than
+ * GitHub hosts the changes: it reaches a mirror that has never heard of
+ * them, and answers with "Could not resolve to a PullRequest with the
+ * number of ...", which reads as a wrong number rather than as the wrong
+ * system. A skill description helps somebody who wonders whether another
+ * tool exists; this is for the case where nobody wondered.
+ *
+ * Only for creating. A create uses the branch in this checkout, so the
+ * checkout's provider is the right question to ask. An edit names a
+ * change that may live in another repo entirely, `-R` and all, so the
+ * skills cover that in words rather than this guessing at it.
+ *
+ * Blocks once and relents on a repeat, the same machinery the title,
+ * section and prose gates use, so it cannot loop and somebody who means
+ * `gh` still gets it on the second try.
+ */
+import { decideGate } from "../../gate/index.js";
+import { resolveRepo } from "../../review/index.js";
+/**
+ * The provider `gh` itself speaks to.
+ *
+ * Named rather than inferred: what makes a redirect necessary is that the
+ * command cannot reach the host, and this is the one host it can.
+ */
+const GITHUB_PROVIDER = "github";
+/**
+ * Redirect a create to the review tools when a provider serves this
+ * checkout. Returns a block, or undefined to let the command through.
+ */
+export async function runRedirectGate(deps, subject) {
+    if (subject.action !== "create")
+        return undefined;
+    const provider = await serving(subject);
+    if (!provider)
+        return undefined;
+    const violations = [
+        { kind: "gh-redirect", found: provider },
+    ];
+    const decision = decideGate(violations, deps.readSignatures(), () => explain(provider), "You have asked for this twice, so it goes through as written. ", `gh-pr-create:${provider}`);
+    if (decision.action === "block") {
+        deps.persistSignature(decision.signature);
+        return { block: true, reason: decision.message };
+    }
+    // On relent the caller has said twice that they mean `gh`. Fall through
+    // to the human review gate rather than blocking again.
+    return undefined;
+}
+/** What to say instead. */
+function explain(provider) {
+    return [
+        `This checkout is served by the ${provider} provider, not by GitHub,`,
+        "so a change created with `gh pr create` would be opened on a mirror",
+        "that nothing reads, or refused outright. Later `gh` commands cannot",
+        'see such a change at all: they answer "Could not resolve to a',
+        'PullRequest with the number of ...", which reads as a wrong number',
+        "and is not one.",
+        "",
+        "Use `review_offer propose` instead. It resolves this repo to",
+        `${provider}, holds the title and body to the same conventions this`,
+        "gate does, and answers with the change's number and URL.",
+        "",
+        "Read the review-guide skill. If you truly mean `gh`, run it again",
+        "and it will go through to the review panel.",
+    ].join("\n");
+}
+/**
+ * The provider that serves this checkout and can open a change, if any.
+ *
+ * Undefined whenever the question cannot be answered: no directory, no
+ * exec, no remote, nothing registered, or a provider that cannot author.
+ * A guardian that cannot tell must not redirect, since blocking a
+ * command for a reason that does not hold is worse than allowing it.
+ */
+async function serving(subject) {
+    const { cwd, exec } = subject;
+    if (!cwd || !exec)
+        return undefined;
+    let remote;
+    try {
+        const result = await exec("git", [
+            "-C",
+            cwd,
+            "remote",
+            "get-url",
+            "origin",
+        ]);
+        remote = result.code === 0 ? result.stdout.trim() : undefined;
+    }
+    catch {
+        // Not a repo, or no git. Nothing to compare, so nothing to say.
+        return undefined;
+    }
+    if (!remote)
+        return undefined;
+    const resolved = resolveRepo({ repoRoot: cwd, remoteUrls: [remote] });
+    if (!resolved.resolved)
+        return undefined;
+    // `gh` is the GitHub CLI, so a repo GitHub serves is the case where it is
+    // the right instrument. Redirecting here said "served by the github
+    // provider, not by GitHub", which contradicts itself, and it would have
+    // blocked every ordinary PR on an ordinary repo.
+    if (resolved.provider.id === GITHUB_PROVIDER)
+        return undefined;
+    // A provider that cannot open a change is no redirect at all, and the
+    // plain git provider claims every checkout.
+    if (!resolved.provider.capabilities(resolved.repo).authoring?.propose) {
+        return undefined;
+    }
+    return resolved.provider.id;
+}

package/dist/internal/guardian/section-gate.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Guardian-side glue for the section gate. Detects invented and
+ * missing sections in a body, asks the pure decision what to do,
+ * and persists a new signature when it blocks. The decision
+ * logic lives in the sections and gate modules; this is only the
+ * read/persist wiring against a caller-supplied signature store.
+ */
+import type { GateDeps } from "../../gate/index.js";
+import type { GuardianResult } from "../../guardian/types.js";
+import { type SectionGateConfig } from "../../sections/index.js";
+/** Run the section gate over a body. Returns a block or undefined. */
+export declare function runSectionGate(deps: GateDeps, body: string | null, config: SectionGateConfig): GuardianResult;
+/**
+ * The relent message, when the section gate is letting this exact
+ * body through after already blocking it once, else null. See
+ * prose-gate.ts's `proseGateNote` for why this exists: a caller
+ * whose "ask" is a synthesized summary, not a full render of the
+ * body, needs to say a relent happened rather than staying silent.
+ */
+export declare function sectionGateNote(deps: GateDeps, body: string | null, config: SectionGateConfig): string | null;

package/dist/internal/guardian/section-gate.js

@@ -0,0 +1,36 @@
+/**
+ * Guardian-side glue for the section gate. Detects invented and
+ * missing sections in a body, asks the pure decision what to do,
+ * and persists a new signature when it blocks. The decision
+ * logic lives in the sections and gate modules; this is only the
+ * read/persist wiring against a caller-supplied signature store.
+ */
+import { sectionGateDecision, } from "../../sections/index.js";
+/** Run the section gate over a body. Returns a block or undefined. */
+export function runSectionGate(deps, body, config) {
+    if (!body)
+        return undefined;
+    const decision = sectionGateDecision(body, deps.readSignatures(), config);
+    if (decision.action === "block") {
+        deps.persistSignature(decision.signature);
+        return { block: true, reason: decision.message };
+    }
+    // On relent the AI already had its chance and could not satisfy
+    // the section set, so blocking again would loop. Fall through to
+    // the human review gate (undefined); the user sees the rendered
+    // body and can reject it. On allow we also fall through.
+    return undefined;
+}
+/**
+ * The relent message, when the section gate is letting this exact
+ * body through after already blocking it once, else null. See
+ * prose-gate.ts's `proseGateNote` for why this exists: a caller
+ * whose "ask" is a synthesized summary, not a full render of the
+ * body, needs to say a relent happened rather than staying silent.
+ */
+export function sectionGateNote(deps, body, config) {
+    if (!body)
+        return null;
+    const decision = sectionGateDecision(body, deps.readSignatures(), config);
+    return decision.action === "relent" ? decision.message : null;
+}

package/dist/internal/guardian/title-gate.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Guardian-side glue for the title gate. Detects conventional
+ * commit format in a PR or issue title, asks the pure decision
+ * what to do, and persists a new signature when it blocks. The
+ * decision logic lives in the title and gate modules; this is only
+ * the read/persist wiring against a caller-supplied signature store.
+ */
+import type { GateDeps } from "../../gate/index.js";
+import type { GuardianResult } from "../../guardian/types.js";
+import { type TitleGateConfig } from "../../title/index.js";
+/** Run the title gate over a title. Returns a block or undefined. */
+export declare function runTitleGate(deps: GateDeps, title: string | null, config: TitleGateConfig): GuardianResult;
+/**
+ * The relent message, when the title gate is letting this exact
+ * title through after already blocking it once, else null. See
+ * prose-gate.ts's `proseGateNote` for why this exists: a caller
+ * whose "ask" is a synthesized summary, not a full render of the
+ * title, needs to say a relent happened rather than staying silent.
+ */
+export declare function titleGateNote(deps: GateDeps, title: string | null, config: TitleGateConfig): string | null;

package/dist/internal/guardian/title-gate.js

@@ -0,0 +1,36 @@
+/**
+ * Guardian-side glue for the title gate. Detects conventional
+ * commit format in a PR or issue title, asks the pure decision
+ * what to do, and persists a new signature when it blocks. The
+ * decision logic lives in the title and gate modules; this is only
+ * the read/persist wiring against a caller-supplied signature store.
+ */
+import { titleGateDecision } from "../../title/index.js";
+/** Run the title gate over a title. Returns a block or undefined. */
+export function runTitleGate(deps, title, config) {
+    if (!title)
+        return undefined;
+    const decision = titleGateDecision(title, deps.readSignatures(), config);
+    if (decision.action === "block") {
+        deps.persistSignature(decision.signature);
+        return { block: true, reason: decision.message };
+    }
+    // On relent the AI already had its chance and could not satisfy
+    // the title convention, so blocking again would loop. Fall
+    // through to the human review gate (undefined); the user sees the
+    // title and can reject it. On allow we also fall through.
+    return undefined;
+}
+/**
+ * The relent message, when the title gate is letting this exact
+ * title through after already blocking it once, else null. See
+ * prose-gate.ts's `proseGateNote` for why this exists: a caller
+ * whose "ask" is a synthesized summary, not a full render of the
+ * title, needs to say a relent happened rather than staying silent.
+ */
+export function titleGateNote(deps, title, config) {
+    if (!title)
+        return null;
+    const decision = titleGateDecision(title, deps.readSignatures(), config);
+    return decision.action === "relent" ? decision.message : null;
+}

package/dist/internal/json-array.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Extract the first balanced JSON array from a string.
+ *
+ * A model reply often wraps its JSON array in prose that itself
+ * contains brackets (`... see line [42]`). A greedy `/\[.*\]/`
+ * spans to the last bracket and fails to parse, silently dropping
+ * the whole payload. This scans from the first `[` to its
+ * matching `]`, respecting string literals and escapes, so the
+ * intended array is recovered regardless of trailing brackets.
+ */
+export declare function firstJsonArray(text: string): string | undefined;

package/dist/internal/json-array.js

@@ -0,0 +1,40 @@
+/**
+ * Extract the first balanced JSON array from a string.
+ *
+ * A model reply often wraps its JSON array in prose that itself
+ * contains brackets (`... see line [42]`). A greedy `/\[.*\]/`
+ * spans to the last bracket and fails to parse, silently dropping
+ * the whole payload. This scans from the first `[` to its
+ * matching `]`, respecting string literals and escapes, so the
+ * intended array is recovered regardless of trailing brackets.
+ */
+export function firstJsonArray(text) {
+    const start = text.indexOf("[");
+    if (start < 0)
+        return undefined;
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = start; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (ch === "\\")
+                escaped = true;
+            else if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"')
+            inString = true;
+        else if (ch === "[")
+            depth++;
+        else if (ch === "]") {
+            depth--;
+            if (depth === 0)
+                return text.slice(start, i + 1);
+        }
+    }
+    return undefined;
+}