@deftai/directive-core 0.108.0 → 0.109.0

package/dist/session/occupancy.js

@@ -40,6 +40,7 @@ import { containedRemove, containedWrite } from "../fs/contained-write.js";
 import { assertWriteTargetSafe } from "../fs/projection-containment.js";
 import { assertAppendLockOwned, withAppendLock } from "../slice/lock.js";
 import { SWARM_WORKER_ROLES } from "../swarm/routing.js";
+import { ambientHostSessionOwner } from "./host-session-owner.js";
 import { stableJson } from "./json.js";
 import { parseTimestamp, timestampIso } from "./time.js";
 export const OCCUPANCY_SCHEMA_VERSION = 1;
@@ -166,6 +167,19 @@ export function occupancyAdmission(record, sessionId, now = new Date()) {
         return "owner";
     return occupancyGrantFor(record, presented, now) === null ? "stranger" : "member";
 }
+// Session ids reach remediation text from operator flags, host environments and
+// whatever a peer wrote into the lease, so a value can carry whitespace or shell
+// metacharacters. Only a value a shell would take as one bare token is inlined
+// into a printed command; anything else keeps its placeholder, because the right
+// quoting differs per shell and a mis-parsed copyable command is worse than one
+// the reader has to fill in. The id itself is still named in the prose above.
+// A leading dash is excluded as well: every CLI parser here reads such a value
+// as another option, so `--occupant --weird-id` fails argument parsing even
+// though the shell itself would have passed the token through intact.
+const SHELL_SAFE_SESSION_ID = /^(?!-)[A-Za-z0-9_.:+=,/-]+$/;
+function commandSessionId(sessionId, placeholder) {
+    return SHELL_SAFE_SESSION_ID.test(sessionId) ? sessionId : placeholder;
+}
 function occupancyClockLine(record) {
     const lastWrite = record.lastWriteAt === null ? "" : ` last_write_at=${timestampIso(record.lastWriteAt)}`;
     return `claimed_at=${timestampIso(record.claimedAt)} heartbeat_at=${timestampIso(record.heartbeatAt)}${lastWrite}`;
@@ -178,7 +192,7 @@ export function formatOccupancyStaleWarning(record, now = new Date(), ttlMs = OC
     const age = heartbeatAgeSeconds(record, now);
     return (`Occupancy lease for session ${record.sessionId} has not beaten for ${age}s of its ` +
         `${Math.round(ttlMs / 1000)}s window; another session may read it as abandoned. ` +
-        `Refresh it with \`deft occupancy:heartbeat --session-id=${record.sessionId}\`.`);
+        `Refresh it with \`deft occupancy:heartbeat --session-id=${commandSessionId(record.sessionId, "<your-session-id>")}\`.`);
 }
 /**
  * Tell the holder its lease aged out of the absolute cap (#3599). Distinct
@@ -191,17 +205,45 @@ export function formatOccupancyAgeCapRemediation(record, now = new Date(), maxLe
         `(claimed ${leaseAgeSeconds(record, now)}s ago, ${occupancyClockLine(record)}), so this ` +
         "worktree is no longer held and a peer may claim it at any moment. Heartbeats cannot " +
         "extend a capped lease — re-claim the worktree with " +
-        `\`deft session:start --session-id=${record.sessionId}\` before writing again.`);
+        `\`deft session:start --session-id=${commandSessionId(record.sessionId, "<your-session-id>")}\` before writing again.`);
 }
-export function formatOccupancyRemediation(record, now = new Date()) {
+/**
+ * Tell a refused caller who holds the lease and what it can actually run.
+ *
+ * `presented` is the id the refused caller offered (#3873). Without it the
+ * message can only print `<your-session-id>` placeholders, which is fine for a
+ * CLI caller that passed its own `--session-id` and useless to a hook process,
+ * which does not know what identity it presented. Passing it also keeps the
+ * message honest when there is none: a grant cannot name an empty child --
+ * `occupancy:grant --child-session-id=` is refused at parse and at membership --
+ * so that remediation is not printed to a caller who could never run it.
+ */
+export function formatOccupancyRemediation(record, now = new Date(), presented) {
     const age = heartbeatAgeSeconds(record, now);
-    return (`Worktree occupied by session ${record.sessionId} (intent=${record.intent}, heartbeat ${age}s ago, ` +
-        `${formatLastWritePhrase(record, now)}, ${occupancyClockLine(record)}).\n` +
+    const header = `Worktree occupied by session ${record.sessionId} (intent=${record.intent}, heartbeat ${age}s ago, ` +
+        `${formatLastWritePhrase(record, now)}, ${occupancyClockLine(record)}).\n`;
+    const tail = "\nThe occupant may release (`occupancy:release` / `session:end`).";
+    if (presented === undefined) {
+        return (`${header}Stay read-only (\`session:start --read-only\`), use another worktree,\n` +
+            "ask the occupant for a write grant (`occupancy:grant --child-session-id=<your-session-id> " +
+            "--role <worker-role>`, run by the occupant), or run a confirmed owner transition " +
+            `(\`session:start --steal --confirm --occupant <reported-session-id> --session-id=<your-session-id>\`).${tail}`);
+    }
+    const actor = presented.trim();
+    const occupantArg = commandSessionId(record.sessionId, "<reported-session-id>");
+    if (actor.length === 0) {
+        return (`${header}This process presented no session identity, so a write grant cannot name it ` +
+            "and an owner transition would not be recognised on its next write.\n" +
+            "Stay read-only (`session:start --read-only`), use another worktree, or ask the occupant " +
+            `to release the lease (\`occupancy:release --session-id=${occupantArg}\` / \`session:end\`).${tail}`);
+    }
+    const actorArg = commandSessionId(actor, "<your-session-id>");
+    return (`${header}This process presented session ${actor}, which neither holds that lease nor has a ` +
+        "write grant on it.\n" +
         "Stay read-only (`session:start --read-only`), use another worktree,\n" +
-        "ask the occupant for a write grant (`occupancy:grant --child-session-id=<your-session-id> " +
+        `ask the occupant for a write grant (\`occupancy:grant --child-session-id=${actorArg} ` +
         "--role <worker-role>`, run by the occupant), or run a confirmed owner transition " +
-        "(`session:start --steal --confirm --occupant <reported-session-id> --session-id=<your-session-id>`).\n" +
-        "The occupant may release (`occupancy:release` / `session:end`).");
+        `(\`session:start --steal --confirm --occupant ${occupantArg} --session-id=${actorArg}\`).${tail}`);
 }
 /**
  * Refuse an administrative verb to a granted child (#3755). Named apart from
@@ -215,13 +257,26 @@ export function formatOccupancyMemberAdministrationRefusal(record, grant, verb)
         "grant never escalates into administration.\n" +
         `Ask the occupant (session ${record.sessionId}) to run it, or wait for the grant to expire.`);
 }
+/**
+ * The owner a claim is made under: an explicit id, then `DEFT_SESSION_ID`, then
+ * the id the running host published, then a mint.
+ *
+ * The host step is what makes an identified host's claim reachable (#3873).
+ * Minting instead binds the lease to an id no later hook process can present,
+ * so the session that claimed the worktree is refused by its own lease. The
+ * mint stays as the last resort for hosts that publish nothing.
+ */
 export function resolveOccupancySessionId(input = {}) {
     const explicit = input.sessionId?.trim();
     if (explicit)
         return explicit;
-    const envId = (input.env ?? process.env).DEFT_SESSION_ID?.trim();
+    const env = input.env ?? process.env;
+    const envId = env.DEFT_SESSION_ID?.trim();
     if (envId)
         return envId;
+    const hostOwner = ambientHostSessionOwner(env);
+    if (hostOwner !== null)
+        return hostOwner;
     return (input.newSessionId ?? randomUUID)();
 }
 export function readOccupancy(projectRoot) {
@@ -596,7 +651,7 @@ export function grantOccupancyMembership(projectRoot, input = {}) {
                 message: capped && current !== null
                     ? formatOccupancyAgeCapRemediation(current, now)
                     : "occupancy:grant found no live lease to grant on. A grant is derived authority, " +
-                        `so claim the worktree first with \`deft session:start --session-id=${owner}\`.`,
+                        `so claim the worktree first with \`deft session:start --session-id=${commandSessionId(owner, "<your-session-id>")}\`.`,
                 code: 1,
             };
         }
@@ -809,7 +864,10 @@ export function evaluateOccupancyWriteGate(projectRoot, input = {}) {
     if (admission === "stranger") {
         return {
             allow: false,
-            message: formatOccupancyRemediation(live, now),
+            // The refused caller is told what identity it actually presented (#3873).
+            // A hook process cannot otherwise know, and the grant this message offers
+            // is only runnable when the occupant can name a non-empty child.
+            message: formatOccupancyRemediation(live, now, incoming),
             occupant: live,
             refreshed: false,
             warning: null,
@@ -974,7 +1032,7 @@ export function heartbeatOccupancy(projectRoot, input = {}) {
             message: capped && existing !== null
                 ? formatOccupancyAgeCapRemediation(existing, now)
                 : "occupancy:heartbeat found no live lease to refresh. Claim one with " +
-                    `\`deft session:start --session-id=${caller}\`.`,
+                    `\`deft session:start --session-id=${commandSessionId(caller, "<your-session-id>")}\`.`,
             code: 1,
         };
     }

package/dist/session/verify-ac-session-cache.d.ts

@@ -4,8 +4,8 @@
  * Disk-backed so check composition (spawned verify:ac) can serve from_cache
  * after a green run in the same session when plan + product hash still match.
  */
-export declare const VERIFY_AC_SESSION_CACHE_DIR = ".deft/verify-ac-session-cache";
-export declare const AC_SERVED_FROM: readonly ["bank", "cache", "executed"];
+export declare const VERIFY_AC_SESSION_CACHE_DIR = ".deft/cache/verify-ac-session-cache";
+export declare const AC_SERVED_FROM: readonly ["bank", "cache", "executed", "refused"];
 export type AcServedFrom = (typeof AC_SERVED_FROM)[number];
 export interface CachedVerifyAcSnapshot {
     readonly ok: boolean;

package/dist/session/verify-ac-session-cache.js

@@ -8,8 +8,8 @@ import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { containedWrite } from "../fs/contained-write.js";
 import { sanitizeScopeIdForFilename } from "./ac-pass-banking.js";
-export const VERIFY_AC_SESSION_CACHE_DIR = ".deft/verify-ac-session-cache";
-export const AC_SERVED_FROM = ["bank", "cache", "executed"];
+export const VERIFY_AC_SESSION_CACHE_DIR = ".deft/cache/verify-ac-session-cache";
+export const AC_SERVED_FROM = ["bank", "cache", "executed", "refused"];
 function asRecord(value) {
     if (typeof value === "object" && value !== null && !Array.isArray(value)) {
         return value;

package/dist/triage/evaluate/worktrees.js

@@ -1,5 +1,7 @@
-import { existsSync, mkdirSync, rmSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { containedRemove, containedWrite } from "../../fs/contained-write.js";
 import { defaultGitRunner as swarmGitRunner, } from "../../swarm/worktrees.js";
 import { evaluatorWorktreePath } from "./paths.js";
 export class EvaluatorWorktreeError extends Error {
@@ -27,17 +29,162 @@ function forceDeleteWorktreeDir(worktreePath) {
     }
     rmSync(worktreePath, { recursive: true, force: true });
 }
+const caseInsensitiveDirCache = new Map();
+function slashResolve(path) {
+    return resolve(path).replace(/\\/g, "/");
+}
+function directoryIgnoresCase(dir) {
+    let existing = resolve(dir);
+    while (!existsSync(existing)) {
+        const parent = dirname(existing);
+        if (parent === existing) {
+            return process.platform === "win32";
+        }
+        existing = parent;
+    }
+    const cached = caseInsensitiveDirCache.get(existing);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const tag = randomBytes(6).toString("hex");
+    const lower = join(existing, `.deft-cs-${tag}a`);
+    const upper = join(existing, `.deft-cs-${tag}A`);
+    let ignores = false;
+    let probed = false;
+    try {
+        containedWrite({
+            root: existing,
+            target: lower,
+            data: "",
+            mode: "create",
+            mkdir: false,
+            mutation: false,
+        });
+        ignores = existsSync(upper);
+        probed = true;
+    }
+    catch {
+        // Fail closed: do not fold unless the probe proved case-insensitivity.
+    }
+    finally {
+        try {
+            containedRemove({ root: existing, target: lower, mutation: false });
+        }
+        catch {
+            // ignore
+        }
+        try {
+            containedRemove({ root: existing, target: upper, mutation: false });
+        }
+        catch {
+            // ignore
+        }
+    }
+    if (probed) {
+        caseInsensitiveDirCache.set(existing, ignores);
+    }
+    return ignores;
+}
+function canonicalizeWorktreePath(path) {
+    const resolved = slashResolve(path);
+    let existing = "";
+    if (existsSync(path)) {
+        existing = path;
+    }
+    else if (existsSync(resolved)) {
+        existing = resolved;
+    }
+    if (existing.length > 0) {
+        try {
+            return realpathSync.native(existing).replace(/\\/g, "/");
+        }
+        catch {
+            // Path vanished between exists and realpath.
+        }
+    }
+    const parent = dirname(resolved);
+    const base = basename(resolved);
+    let parentCanon = slashResolve(parent);
+    try {
+        if (existsSync(parent)) {
+            parentCanon = realpathSync.native(parent).replace(/\\/g, "/");
+        }
+    }
+    catch {
+        // Keep slash-resolved parent.
+    }
+    const leaf = directoryIgnoresCase(parent) ? base.toLowerCase() : base;
+    return `${parentCanon}/${leaf}`;
+}
+/**
+ * Unregister one missing worktree by deleting only its `$GIT_DIR/worktrees/<id>`
+ * admin directory. Containment root is that worktrees dir (the git common dir
+ * may sit outside a linked-worktree projectRoot). `git worktree prune` has no
+ * path argument and operates on every registration, including concurrent
+ * agents' reflogs.
+ *
+ * Path identity uses on-disk realpath when the worktree exists, and otherwise
+ * folds case only when the parent directory is case-insensitive. A case-sensitive
+ * Windows directory can host two worktrees that differ only by case; those
+ * must not share an admin entry.
+ */
+function pruneEvaluatorWorktreeAdmin(git, projectRoot, worktreePath) {
+    const common = git(["rev-parse", "--git-common-dir"], projectRoot);
+    const trimmed = common.stdout.trim();
+    if (common.returncode !== 0 || trimmed.length === 0) {
+        return;
+    }
+    const commonDir = isAbsolute(trimmed) ? resolve(trimmed) : resolve(projectRoot, trimmed);
+    const worktreesDir = join(commonDir, "worktrees");
+    if (!existsSync(worktreesDir)) {
+        return;
+    }
+    const needle = canonicalizeWorktreePath(worktreePath);
+    let names = [];
+    try {
+        names = readdirSync(worktreesDir);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (name === "." || name === ".." || name.includes("/") || name.includes("\\")) {
+            continue;
+        }
+        const gitdirFile = join(worktreesDir, name, "gitdir");
+        if (!existsSync(gitdirFile)) {
+            continue;
+        }
+        let recorded = "";
+        try {
+            recorded = readFileSync(gitdirFile, "utf8").trim();
+        }
+        catch {
+            continue;
+        }
+        const recordedWorktree = recorded.replace(/\\/g, "/").replace(/\/\.git$/u, "");
+        if (canonicalizeWorktreePath(recordedWorktree) === needle) {
+            containedRemove({
+                root: resolve(worktreesDir),
+                target: join(worktreesDir, name),
+                recursive: true,
+                mutation: false,
+            });
+            return;
+        }
+    }
+}
 function worktreeStillRegistered(git, projectRoot, worktreePath) {
     const listed = git(["worktree", "list", "--porcelain"], projectRoot);
     if (listed.returncode !== 0) {
         return true;
     }
-    const needle = resolve(worktreePath).replace(/\\/g, "/").toLowerCase();
+    const needle = canonicalizeWorktreePath(worktreePath);
     for (const line of listed.stdout.split(/\r?\n/u)) {
         if (!line.startsWith("worktree ")) {
             continue;
         }
-        const listedPath = line.slice("worktree ".length).replace(/\\/g, "/").toLowerCase();
+        const listedPath = canonicalizeWorktreePath(line.slice("worktree ".length));
         if (listedPath === needle) {
             return true;
         }
@@ -53,13 +200,13 @@ export function removeEvaluatorWorktree(projectRoot, worktreePath, git = swarmGi
     }
     const firstError = proc.stderr.trim() || "<no stderr>";
     forceDeleteWorktreeDir(worktreePath);
-    runner(["worktree", "prune"], projectRoot);
+    pruneEvaluatorWorktreeAdmin(runner, projectRoot, worktreePath);
     const retry = runner(["worktree", "remove", "--force", worktreePath], projectRoot);
     if (retry.returncode === 0) {
         return;
     }
     forceDeleteWorktreeDir(worktreePath);
-    runner(["worktree", "prune"], projectRoot);
+    pruneEvaluatorWorktreeAdmin(runner, projectRoot, worktreePath);
     if (!worktreeStillRegistered(runner, projectRoot, worktreePath) && !existsSync(worktreePath)) {
         return;
     }

package/dist/umbrella-current-shape/index.d.ts

@@ -93,6 +93,27 @@ export interface CurrentShapeSidecar {
     readonly authorAssociation: string;
     readonly body: string;
 }
+/** A shape-shaped comment dropped by the #2307 authorship filter (#3934). */
+export interface DiscardedShapeCandidate {
+    readonly commentId: number;
+    /** Normalized `author_association` -- never comment text. */
+    readonly authorAssociation: string;
+}
+/**
+ * Why `selectCurrentShapeComment` returned null (#3934). Advisory: it is not
+ * consumed by any gate, exit code, or count.
+ */
+export interface CurrentShapeNullReason {
+    readonly kind: "no-shape-comment" | "non-maintainer-shape";
+    readonly discarded: readonly DiscardedShapeCandidate[];
+    readonly message: string;
+}
+/** Sidecar payload, or the reason none was selectable (#3934). */
+export interface CurrentShapeSidecarOutcome {
+    readonly sidecar: CurrentShapeSidecar | null;
+    /** Non-null exactly when `sidecar` is null. */
+    readonly reason: CurrentShapeNullReason | null;
+}
 /** True when labels or sub-issue summary mark the issue as umbrella/tracker-like. */
 export declare function isUmbrellaLikeIssue(raw: Record<string, unknown>): boolean;
 /** Normalize a raw issue payload's comment array (REST or pre-mapped). */
@@ -104,13 +125,28 @@ export declare function commentsFromRawPayload(raw: Record<string, unknown>): Is
 export declare function countMaintainerCurrentShapeComments(comments: readonly IssueComment[]): number;
 /** Markdown section appended to cache content.md when a canonical shape exists. */
 export declare function formatCurrentShapeSection(selected: CurrentShapeComment): string;
+/** Advisory cache note for a selected-null thread that had discarded candidates (#3934). */
+export declare function formatCurrentShapeNotSelectedSection(reason: CurrentShapeNullReason): string;
 /**
  * Append the canonical current-shape comment (if any) to a rendered cache body.
- * Returns the input unchanged when no maintainer-authored current-shape exists.
+ *
+ * When nothing is selectable but the thread carried shape-shaped comments that
+ * the #2307 authorship filter dropped, append the advisory not-selected note
+ * instead of returning the body unchanged (#3934): an agent reading content.md
+ * without invoking `umbrella:current-shape` would otherwise see only the stale
+ * body the #1152 rule tells it to distrust. A thread with no shape comment at
+ * all is still returned unchanged, so ordinary issues gain no note.
  */
 export declare function appendCurrentShapeSection(baseContent: string, raw: Record<string, unknown>): string;
-/** Build the current-shape.json sidecar payload, or null when none is selectable. */
-export declare function buildCurrentShapeSidecar(raw: Record<string, unknown>): CurrentShapeSidecar | null;
+/**
+ * Build the current-shape.json sidecar payload.
+ *
+ * Reports why nothing was selectable rather than returning a bare null (#3934),
+ * so a caller can tell "no shape comment on this thread" from "a shape comment
+ * exists but its author is outside MAINTAINER_ASSOCIATIONS". Advisory only --
+ * no sidecar is written on either null kind, exactly as before.
+ */
+export declare function buildCurrentShapeSidecar(raw: Record<string, unknown>): CurrentShapeSidecarOutcome;
 /** Merge `gh api --paginate` concatenated JSON array pages into comment rows. */
 export declare function parseCommentsFromGhStdout(stdout: string): IssueComment[];
 export declare function extractPassFromBody(body: string): number | null;
@@ -128,6 +164,18 @@ export declare function detectSections(body: string): SectionPresence;
 export declare function sectionsRecord(presence: SectionPresence): Record<string, boolean>;
 export declare const NO_CURRENT_SHAPE_MESSAGE: string;
 export declare const NON_MAINTAINER_CURRENT_SHAPE_MESSAGE: string;
+/** Bound the diagnostic so one forged thread cannot flood a cache note (#3934). */
+export declare const MAX_REPORTED_DISCARDED_CANDIDATES = 5;
+/**
+ * Classify a null return from `selectCurrentShapeComment` (#3934).
+ *
+ * Advisory only: it changes no selection, no maintainer count, and no exit code.
+ * Discarded candidates are named by comment id and normalized author
+ * association; a comment body is never reproduced, because forwarding untrusted
+ * text into a cache or xBRIEF narrative is the injection this filter exists to
+ * refuse (#2307).
+ */
+export declare function describeCurrentShapeNull(comments: readonly IssueComment[]): CurrentShapeNullReason;
 export declare function fetchCurrentShape(options: {
     repo: string;
     issueNumber: number;

package/dist/umbrella-current-shape/index.js

@@ -1,6 +1,6 @@
 import { spawnSync } from "node:child_process";
 import { scan } from "../cache/scanner.js";
-import { resolveBinary } from "../scm/binary.js";
+import { resolveBinaryForArgv } from "../scm/call-shape.js";
 import { SUBPROCESS_MAX_BUFFER } from "../subprocess/max-buffer.js";
 import { resolveRepo } from "../triage/queue/repo.js";
 /**
@@ -192,30 +192,64 @@ export function formatCurrentShapeSection(selected) {
         "",
     ].join("\n");
 }
+/** Advisory cache note for a selected-null thread that had discarded candidates (#3934). */
+export function formatCurrentShapeNotSelectedSection(reason) {
+    return [
+        "",
+        "---",
+        "",
+        "## Canonical current shape: not selected (#1152 / #2307)",
+        "",
+        `_${reason.message} Deterministic read path: \`task umbrella:current-shape <N>\`._`,
+        "",
+    ].join("\n");
+}
 /**
  * Append the canonical current-shape comment (if any) to a rendered cache body.
- * Returns the input unchanged when no maintainer-authored current-shape exists.
+ *
+ * When nothing is selectable but the thread carried shape-shaped comments that
+ * the #2307 authorship filter dropped, append the advisory not-selected note
+ * instead of returning the body unchanged (#3934): an agent reading content.md
+ * without invoking `umbrella:current-shape` would otherwise see only the stale
+ * body the #1152 rule tells it to distrust. A thread with no shape comment at
+ * all is still returned unchanged, so ordinary issues gain no note.
  */
 export function appendCurrentShapeSection(baseContent, raw) {
-    const selected = selectCurrentShapeComment(commentsFromRawPayload(raw));
+    const comments = commentsFromRawPayload(raw);
+    const selected = selectCurrentShapeComment(comments);
     if (selected === null) {
-        return baseContent;
+        const reason = describeCurrentShapeNull(comments);
+        if (reason.kind !== "non-maintainer-shape") {
+            return baseContent;
+        }
+        return `${baseContent.trimEnd()}\n${formatCurrentShapeNotSelectedSection(reason)}`;
     }
     return `${baseContent.trimEnd()}\n${formatCurrentShapeSection(selected)}`;
 }
-/** Build the current-shape.json sidecar payload, or null when none is selectable. */
+/**
+ * Build the current-shape.json sidecar payload.
+ *
+ * Reports why nothing was selectable rather than returning a bare null (#3934),
+ * so a caller can tell "no shape comment on this thread" from "a shape comment
+ * exists but its author is outside MAINTAINER_ASSOCIATIONS". Advisory only --
+ * no sidecar is written on either null kind, exactly as before.
+ */
 export function buildCurrentShapeSidecar(raw) {
-    const selected = selectCurrentShapeComment(commentsFromRawPayload(raw));
+    const comments = commentsFromRawPayload(raw);
+    const selected = selectCurrentShapeComment(comments);
     if (selected === null) {
-        return null;
+        return { sidecar: null, reason: describeCurrentShapeNull(comments) };
     }
     return {
-        commentId: selected.id,
-        htmlUrl: selected.htmlUrl,
-        pass: selected.pass,
-        authorLogin: selected.authorLogin,
-        authorAssociation: selected.authorAssociation,
-        body: selected.body,
+        sidecar: {
+            commentId: selected.id,
+            htmlUrl: selected.htmlUrl,
+            pass: selected.pass,
+            authorLogin: selected.authorLogin,
+            authorAssociation: selected.authorAssociation,
+            body: selected.body,
+        },
+        reason: null,
     };
 }
 /** Merge `gh api --paginate` concatenated JSON array pages into comment rows. */
@@ -278,9 +312,10 @@ export function parseCommentsFromGhStdout(stdout) {
     return comments;
 }
 function defaultFetchComments(repo, issueNumber) {
-    const binary = resolveBinary();
     const path = `repos/${repo}/issues/${issueNumber}/comments?per_page=100`;
-    const proc = spawnSync(binary, ["api", "--paginate", path], {
+    const apiArgs = ["--paginate", path];
+    const binary = resolveBinaryForArgv("api", apiArgs);
+    const proc = spawnSync(binary, ["api", ...apiArgs], {
         encoding: "utf8",
         maxBuffer: SUBPROCESS_MAX_BUFFER,
     });
@@ -385,6 +420,58 @@ export const NON_MAINTAINER_CURRENT_SHAPE_MESSAGE = "A ## Current shape (as of p
     "non-maintainer (author_association not in OWNER/MEMBER/COLLABORATOR) and is " +
     "ignored per AGENTS.md ## Umbrella current-shape convention (#1152 / #2307). " +
     "A maintainer must (re-)post the current-shape comment for it to be authoritative.";
+/** Bound the diagnostic so one forged thread cannot flood a cache note (#3934). */
+export const MAX_REPORTED_DISCARDED_CANDIDATES = 5;
+const SAFE_ASSOCIATION_RE = /^[A-Z_]{1,32}$/;
+/**
+ * GitHub sets `author_association` from a fixed enum, but a replayed or
+ * hand-built payload can carry anything. Normalizing keeps the diagnostic from
+ * smuggling arbitrary payload text into an agent-facing surface (#3934).
+ */
+function normalizeAssociation(raw) {
+    const upper = raw.trim().toUpperCase();
+    return SAFE_ASSOCIATION_RE.test(upper) ? upper : "UNKNOWN";
+}
+function formatDiscardedCandidates(discarded) {
+    const shown = discarded
+        .slice(0, MAX_REPORTED_DISCARDED_CANDIDATES)
+        .map((candidate) => `comment ${candidate.commentId} (${candidate.authorAssociation})`);
+    const hidden = discarded.length - shown.length;
+    return hidden > 0 ? `${shown.join(", ")}, and ${hidden} more` : shown.join(", ");
+}
+/**
+ * Classify a null return from `selectCurrentShapeComment` (#3934).
+ *
+ * Advisory only: it changes no selection, no maintainer count, and no exit code.
+ * Discarded candidates are named by comment id and normalized author
+ * association; a comment body is never reproduced, because forwarding untrusted
+ * text into a cache or xBRIEF narrative is the injection this filter exists to
+ * refuse (#2307).
+ */
+export function describeCurrentShapeNull(comments) {
+    const discarded = [];
+    for (const comment of comments) {
+        if (isMaintainerAuthored(comment.authorAssociation)) {
+            continue;
+        }
+        if (extractPassFromBody(comment.body) === null) {
+            continue;
+        }
+        discarded.push({
+            commentId: comment.id,
+            authorAssociation: normalizeAssociation(comment.authorAssociation),
+        });
+    }
+    if (discarded.length === 0) {
+        return { kind: "no-shape-comment", discarded: [], message: NO_CURRENT_SHAPE_MESSAGE };
+    }
+    return {
+        kind: "non-maintainer-shape",
+        discarded,
+        message: `${NON_MAINTAINER_CURRENT_SHAPE_MESSAGE} ` +
+            `Discarded candidate(s): ${formatDiscardedCandidates(discarded)}.`,
+    };
+}
 export function fetchCurrentShape(options) {
     const fetcher = options.fetchComments ?? defaultFetchComments;
     const fetched = fetcher(options.repo, options.issueNumber);
@@ -393,11 +480,12 @@ export function fetchCurrentShape(options) {
     }
     const selected = selectCurrentShapeComment(fetched);
     if (selected === null) {
-        // Distinguish provenance-filtered absence from genuine absence (#2307).
-        const hadNonMaintainerShape = fetched.some((c) => extractPassFromBody(c.body) !== null && !isMaintainerAuthored(c.authorAssociation));
+        // Distinguish provenance-filtered absence from genuine absence (#2307), via
+        // the same classifier the cache-side callers use (#3934). The CLI keeps its
+        // two existing messages verbatim -- discarded ids stay off this surface.
         return {
             ok: false,
-            error: hadNonMaintainerShape
+            error: describeCurrentShapeNull(fetched).kind === "non-maintainer-shape"
                 ? NON_MAINTAINER_CURRENT_SHAPE_MESSAGE
                 : NO_CURRENT_SHAPE_MESSAGE,
             kind: "not-found",

package/dist/validate-content/deposit-required.d.ts

@@ -0,0 +1,39 @@
+/**
+ * C1 declared deposit closure (#3601 / #3899).
+ *
+ * Required consumer-deposit paths are a closed typed declaration, not a
+ * regex over AGENTS.md RFC2119 prose. Existence checks reuse existsSync
+ * the same way validate-links.ts does, against a staged pack root (the
+ * prepack flatten), not the source checkout.
+ */
+export declare const DEPOSIT_REQUIRED_SCHEMA: "deft.deposit-required-paths.v1";
+export declare const DEPOSIT_REQUIRED_REL = "contracts/deposit-required-paths.json";
+export declare const DEPOSIT_PREFIX = ".deft/core/";
+export interface DepositRequiredDeclaration {
+    readonly schema: typeof DEPOSIT_REQUIRED_SCHEMA;
+    readonly paths: readonly string[];
+}
+export interface DepositClosureResult {
+    readonly ok: boolean;
+    readonly missing: readonly string[];
+    readonly checked: number;
+}
+export declare function extractDepositRequiredComments(source: string): string[];
+export declare function parseDepositRequiredDeclaration(jsonText: string): DepositRequiredDeclaration;
+export declare function packRelativeFromDepositPath(declared: string): string;
+/** Prepack mapping used by @deftai/directive-content. */
+export declare function sourcePathForPackRelative(repoRoot: string, packRelative: string): string;
+export declare function evaluateDepositClosure(options: {
+    readonly packRoot: string;
+    readonly paths: readonly string[];
+}): DepositClosureResult;
+export declare function loadDepositRequiredDeclaration(filePath: string): DepositRequiredDeclaration;
+export declare function resolveDeclarationFile(root: string): string | null;
+export declare function evaluateInstalledDepositClosure(projectRoot: string): {
+    readonly skipped: boolean;
+    readonly missing: readonly string[];
+    readonly declarationPath: string | null;
+    readonly error: string | null;
+};
+export declare function renderDeclaredDepositClosureLine(result: ReturnType<typeof evaluateInstalledDepositClosure>): string;
+//# sourceMappingURL=deposit-required.d.ts.map