@event4u/agent-config 9.8.0 → 9.9.0

package/src/scripts/self_review_gate.test.ts

@@ -1,11 +1,19 @@
-import { describe, expect, it } from 'vitest';
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
 
 import {
     LARGE_DIFF_LINES,
+    buildPlan,
     classifyBlocking,
+    detectReleaseVersion,
     escalationReasons,
     gateVerdict,
     isReviewablePath,
+    pickPreviousTag,
     renderReview,
     type Finding,
 } from './self_review_gate.js';
@@ -122,3 +130,167 @@ describe('renderReview — escalation banner', () => {
         expect(out).toContain('Escalation warranted');
     });
 });
+
+// ── Release-PR review mode (road-to-feedback-9.2.0-followups Phase 3) ──
+// See docs/design/release-pr-review-mode.md — anchored to the PR #957
+// false-advisory case (release features reading as "not in the diff").
+
+describe('detectReleaseVersion', () => {
+    const changelogAdd = (v: string) =>
+        `+## [${v}](https://github.com/event4u-app/agent-config/compare/9.1.0...${v}) (2026-07-14)`;
+    const packageAdd = (v: string) => `+    "version": "${v}",`;
+
+    it('detects a release PR when the changelog heading and the package.json bump agree', () => {
+        const patch = [
+            'diff --git a/CHANGELOG.md b/CHANGELOG.md',
+            '@@ -14,6 +14,8 @@',
+            ' ## [Unreleased]',
+            '+',
+            changelogAdd('9.2.0'),
+            'diff --git a/package.json b/package.json',
+            '@@ -1,6 +1,6 @@',
+            '-    "version": "9.1.0",',
+            packageAdd('9.2.0'),
+        ].join('\n');
+        expect(detectReleaseVersion(patch)).toBe('9.2.0');
+    });
+
+    it('is NOT a release PR when only the changelog heading changed (no version bump)', () => {
+        expect(detectReleaseVersion(changelogAdd('9.2.0'))).toBeNull();
+    });
+
+    it('is NOT a release PR when only package.json bumped (no changelog heading)', () => {
+        expect(detectReleaseVersion(packageAdd('9.2.0'))).toBeNull();
+    });
+
+    it('is NOT a release PR on a normal feature-PR patch (neither signal present)', () => {
+        const patch = ['+export function foo() {}', '-export function bar() {}'].join('\n');
+        expect(detectReleaseVersion(patch)).toBeNull();
+    });
+
+    it('refuses to guess when the changelog and package.json versions disagree', () => {
+        const patch = [changelogAdd('9.2.0'), packageAdd('9.3.0')].join('\n');
+        expect(detectReleaseVersion(patch)).toBeNull();
+    });
+
+    it('ignores removed lines (the old version) and reads only the added one', () => {
+        const patch = ['-    "version": "9.1.0",', packageAdd('9.2.0'), changelogAdd('9.2.0')].join('\n');
+        expect(detectReleaseVersion(patch)).toBe('9.2.0');
+    });
+});
+
+describe('pickPreviousTag', () => {
+    it('picks the highest tag strictly below the release version', () => {
+        expect(pickPreviousTag('9.2.0', ['9.0.0', '9.1.0', '9.2.0'])).toBe('9.1.0');
+    });
+    it('handles a v-prefixed tag naming convention', () => {
+        expect(pickPreviousTag('9.2.0', ['v9.0.0', 'v9.1.0'])).toBe('v9.1.0');
+    });
+    it('returns null when no tag is strictly below the version', () => {
+        expect(pickPreviousTag('9.2.0', ['9.2.0', '9.3.0'])).toBeNull();
+        expect(pickPreviousTag('9.2.0', [])).toBeNull();
+    });
+    it('ignores non-semver tags (branch-backup names etc.) instead of crashing', () => {
+        expect(
+            pickPreviousTag('9.2.0', [
+                'backup/pre-rebase-augment-limit-fit',
+                '9.1.0',
+                'local-squashed-tip-2026-05-18',
+            ]),
+        ).toBe('9.1.0');
+    });
+});
+
+describe('buildPlan — release-PR shape (PR #957 reproduction)', () => {
+    function git(root: string, ...args: string[]) {
+        return spawnSync('git', args, {
+            cwd: root,
+            encoding: 'utf8',
+            env: {
+                ...process.env,
+                GIT_AUTHOR_NAME: 'T',
+                GIT_AUTHOR_EMAIL: 't@e.test',
+                GIT_COMMITTER_NAME: 'T',
+                GIT_COMMITTER_EMAIL: 't@e.test',
+            },
+        });
+    }
+    function write(root: string, rel: string, content: string): void {
+        const full = path.join(root, rel);
+        fs.mkdirSync(path.dirname(full), { recursive: true });
+        fs.writeFileSync(full, content, 'utf-8');
+    }
+    function mkTmp(): string {
+        return fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'srg-')));
+    }
+
+    let root: string | undefined;
+    afterEach(() => {
+        if (root) fs.rmSync(root, { recursive: true, force: true });
+        root = undefined;
+    });
+
+    it('release mode sees the pre-cut feature file; the packaging diff alone does not (PR #957 shape)', () => {
+        root = mkTmp();
+        git(root, 'init', '-q', '-b', 'main');
+        write(root, 'package.json', '{\n  "name": "x",\n  "version": "9.0.0"\n}\n');
+        write(root, 'CHANGELOG.md', '# Changelog\n\n## [Unreleased]\n');
+        git(root, 'add', '-A');
+        git(root, 'commit', '-q', '-m', 'baseline');
+        git(root, 'tag', '9.1.0'); // the previous release tag
+
+        // The feature merges into main BEFORE the release cut — the PR #957 shape.
+        write(root, 'feature.txt', 'new cross-source-consistency rule content\n');
+        git(root, 'add', '-A');
+        git(root, 'commit', '-q', '-m', 'feat: cross-source-consistency');
+
+        // Release branch cut from main's current tip — no divergence yet, so
+        // main...release-branch only shows the release-cut commit below.
+        git(root, 'checkout', '-q', '-b', 'release-branch');
+        write(
+            root,
+            'CHANGELOG.md',
+            '# Changelog\n\n## [Unreleased]\n\n' +
+                '## [9.2.0](https://github.com/event4u-app/agent-config/compare/9.1.0...9.2.0) (2026-07-14)\n',
+        );
+        write(root, 'package.json', '{\n  "name": "x",\n  "version": "9.2.0"\n}\n');
+        git(root, 'add', '-A');
+        git(root, 'commit', '-q', '-m', 'chore(release): 9.2.0');
+
+        const plan = buildPlan('main', root);
+
+        expect(plan.release?.version).toBe('9.2.0');
+        expect(plan.release?.previousTag).toBe('9.1.0');
+        // The packaging diff (main...HEAD) alone does NOT show the pre-cut
+        // feature — the exact false-advisory shape PR #957 hit.
+        expect(plan.release?.packagingFiles).not.toContain('feature.txt');
+        expect(plan.release?.packagingFiles).toEqual(
+            expect.arrayContaining(['CHANGELOG.md', 'package.json']),
+        );
+        // Release mode's actual analysis range (previousTag...HEAD) DOES
+        // include it — this is what stops "feature not in diff" recurring.
+        expect(plan.files).toContain('feature.txt');
+        expect(plan.analysisBase).toBe('9.1.0');
+    });
+
+    it('a normal feature PR (no changelog/version bump) uses the unchanged base', () => {
+        root = mkTmp();
+        git(root, 'init', '-q', '-b', 'main');
+        write(root, 'package.json', '{\n  "name": "x",\n  "version": "9.1.0"\n}\n');
+        write(root, 'CHANGELOG.md', '# Changelog\n\n## [Unreleased]\n');
+        git(root, 'add', '-A');
+        git(root, 'commit', '-q', '-m', 'baseline');
+        git(root, 'tag', '9.1.0');
+
+        git(root, 'checkout', '-q', '-b', 'feature-branch');
+        write(root, 'feature.txt', 'some feature\n');
+        git(root, 'add', '-A');
+        git(root, 'commit', '-q', '-m', 'feat: add feature');
+
+        const plan = buildPlan('main', root);
+
+        expect(plan.release).toBeUndefined();
+        expect(plan.analysisBase).toBe('main');
+        expect(plan.files).toContain('feature.txt');
+    });
+});

package/src/scripts/self_review_gate.ts

@@ -83,9 +83,9 @@ export function isReviewablePath(p: string): boolean {
     return !SKIP_PREFIXES.some((pre) => p.startsWith(pre));
 }
 
-function changedFiles(baseRef: string): string[] {
+function changedFiles(baseRef: string, cwd: string = REPO_ROOT): string[] {
     const r = spawnSync('git', ['diff', '--name-only', `${baseRef}...HEAD`], {
-        cwd: REPO_ROOT,
+        cwd,
         encoding: 'utf8',
     });
     if (r.status !== 0) {
@@ -98,10 +98,10 @@ function changedFiles(baseRef: string): string[] {
         .filter(isReviewablePath);
 }
 
-function diffText(baseRef: string, files: string[]): string {
+function diffText(baseRef: string, files: string[], cwd: string = REPO_ROOT): string {
     if (files.length === 0) return '';
     const r = spawnSync('git', ['diff', `${baseRef}...HEAD`, '--', ...files], {
-        cwd: REPO_ROOT,
+        cwd,
         encoding: 'utf8',
         maxBuffer: 32 * 1024 * 1024,
     });
@@ -109,10 +109,10 @@ function diffText(baseRef: string, files: string[]): string {
 }
 
 /** Sum of added+deleted lines across `files` (binary files count 0). */
-function changedLineCount(baseRef: string, files: string[]): number {
+function changedLineCount(baseRef: string, files: string[], cwd: string = REPO_ROOT): number {
     if (files.length === 0) return 0;
     const r = spawnSync('git', ['diff', '--numstat', `${baseRef}...HEAD`, '--', ...files], {
-        cwd: REPO_ROOT,
+        cwd,
         encoding: 'utf8',
         maxBuffer: 32 * 1024 * 1024,
     });
@@ -124,6 +124,94 @@ function changedLineCount(baseRef: string, files: string[]): number {
     return total;
 }
 
+// ── Release-PR detection (road-to-feedback-9.2.0-followups Phase 3) ────
+/**
+ * A release PR is detected from its own packaging diff (baseRef...HEAD,
+ * scoped to CHANGELOG.md + package.json): an added changelog heading and an
+ * added package.json version bump, agreeing on the same version. Pure over
+ * the patch text — no git call — so it is unit-testable with synthetic
+ * patches. See docs/design/release-pr-review-mode.md.
+ */
+export function detectReleaseVersion(patchText: string): string | null {
+    const addedLines = patchText
+        .split('\n')
+        .filter((l) => l.startsWith('+') && !l.startsWith('+++'))
+        .map((l) => l.slice(1));
+
+    let changelogVersion: string | null = null;
+    let packageVersion: string | null = null;
+    for (const line of addedLines) {
+        const changelogMatch = /^##\s*\[(\d+\.\d+\.\d+)\]/.exec(line);
+        if (changelogMatch) changelogVersion = changelogMatch[1] ?? null;
+        const packageMatch = /^\s*"version"\s*:\s*"(\d+\.\d+\.\d+)"/.exec(line);
+        if (packageMatch) packageVersion = packageMatch[1] ?? null;
+    }
+    if (changelogVersion && packageVersion && changelogVersion === packageVersion) {
+        return changelogVersion;
+    }
+    return null;
+}
+
+function releaseDetectionPatch(baseRef: string, cwd: string): string {
+    const r = spawnSync('git', ['diff', `${baseRef}...HEAD`, '--', 'CHANGELOG.md', 'package.json'], {
+        cwd,
+        encoding: 'utf8',
+        maxBuffer: 8 * 1024 * 1024,
+    });
+    return (r.stdout ?? '').toString();
+}
+
+/** Impure wrapper: collects the packaging patch via git, then detects. */
+export function detectReleaseVersionFromGit(baseRef: string, cwd: string = REPO_ROOT): string | null {
+    return detectReleaseVersion(releaseDetectionPatch(baseRef, cwd));
+}
+
+/** `major.minor.patch`, tolerating an optional `v` prefix; null if not semver-shaped. */
+function parseSemver(raw: string): [number, number, number] | null {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(raw.trim());
+    if (!m) return null;
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+function semverLessThan(a: [number, number, number], b: [number, number, number]): boolean {
+    const [aMajor, aMinor, aPatch] = a;
+    const [bMajor, bMinor, bPatch] = b;
+    if (aMajor !== bMajor) return aMajor < bMajor;
+    if (aMinor !== bMinor) return aMinor < bMinor;
+    return aPatch < bPatch;
+}
+
+/**
+ * Highest semver-shaped tag strictly below `version`, or null if none. Pure
+ * over the supplied tag list — no git call. Non-semver tags (branch-backup
+ * names etc.) are ignored rather than throwing.
+ */
+export function pickPreviousTag(version: string, tags: readonly string[]): string | null {
+    const target = parseSemver(version);
+    if (!target) return null;
+    let best: { raw: string; parsed: [number, number, number] } | null = null;
+    for (const raw of tags) {
+        const parsed = parseSemver(raw);
+        if (!parsed) continue;
+        if (!semverLessThan(parsed, target)) continue;
+        if (!best || semverLessThan(best.parsed, parsed)) best = { raw, parsed };
+    }
+    return best ? best.raw : null;
+}
+
+function listGitTags(cwd: string): string[] {
+    const r = spawnSync('git', ['tag'], { cwd, encoding: 'utf8' });
+    return (r.stdout ?? '')
+        .split('\n')
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+
+/** Impure wrapper: lists tags via git, then picks the previous one. */
+export function resolvePreviousTagFromGit(version: string, cwd: string = REPO_ROOT): string | null {
+    return pickPreviousTag(version, listGitTags(cwd));
+}
+
 // ── Escalation classifier (large / claim-affecting → full ai-council) ──
 /**
  * A large or claim-affecting diff warrants the FULL `ai-council` (advisor
@@ -157,9 +245,31 @@ function loadSkillBody(name: string): string {
     return readFileSync(p, 'utf8');
 }
 
-function buildSystemPrompt(): string {
+/** Info about a detected release PR — see docs/design/release-pr-review-mode.md. */
+export interface ReleaseInfo {
+    version: string;
+    previousTag: string;
+    /** Files touched by the packaging diff (baseRef...HEAD) — for context only. */
+    packagingFiles: string[];
+}
+
+/**
+ * Release-mode note appended to the system prompt so the model analyzes the
+ * feature range instead of reporting release features as "not in the diff"
+ * (the PR #957 false-advisory shape — see docs/design/release-pr-review-mode.md).
+ */
+function releaseNoteText(release: ReleaseInfo, baseRef: string): string {
+    const fileList = release.packagingFiles.length > 0 ? release.packagingFiles.join(', ') : '(none)';
+    return (
+        `\n\nRelease PR for ${release.version}: analysis range is ${release.previousTag}...HEAD ` +
+        `(the full release commit range). The packaging diff vs ${baseRef} touches: ${fileList}. ` +
+        "Do NOT report a feature as 'not in the diff' when it is present in the release range."
+    );
+}
+
+function buildSystemPrompt(release?: ReleaseInfo, baseRef?: string): string {
     const bodies = REVIEW_SKILLS.map((s) => `# Skill: ${s}\n\n${loadSkillBody(s)}`).join('\n\n---\n\n');
-    return [
+    const base = [
         'You are the self-review gate for an AI-agent governance package. Apply the',
         'two skills below to the supplied PR diff. Return ONLY a JSON object of the',
         'shape {"findings":[{"severity":"critical|high|medium|low",',
@@ -170,6 +280,7 @@ function buildSystemPrompt(): string {
         '',
         bodies,
     ].join('\n');
+    return release && baseRef ? base + releaseNoteText(release, baseRef) : base;
 }
 
 // ── Plan (dry-run) ────────────────────────────────────────────────────
@@ -179,22 +290,47 @@ export interface ReviewPlan {
     promptChars: number;
     note: string;
     escalation: string[];
+    /** The base actually analyzed for `files`/diff: `baseRef`, or `release.previousTag`. */
+    analysisBase: string;
+    /** Present iff a release PR was detected — see docs/design/release-pr-review-mode.md. */
+    release?: ReleaseInfo;
 }
 
-export function buildPlan(baseRef: string): ReviewPlan {
-    const files = changedFiles(baseRef);
-    const diff = diffText(baseRef, files);
-    const escalation = escalationReasons(files, changedLineCount(baseRef, files));
+export function buildPlan(baseRef: string, cwd: string = REPO_ROOT): ReviewPlan {
+    const packagingFiles = changedFiles(baseRef, cwd);
+    const releaseVersion = detectReleaseVersionFromGit(baseRef, cwd);
+
+    let release: ReleaseInfo | undefined;
+    let analysisBase = baseRef;
+    if (releaseVersion) {
+        const previousTag = resolvePreviousTagFromGit(releaseVersion, cwd);
+        if (previousTag) {
+            release = { version: releaseVersion, previousTag, packagingFiles };
+            analysisBase = previousTag;
+        } else {
+            process.stdout.write(
+                `::notice::self-review-gate — release ${releaseVersion} detected but no previous tag ` +
+                    `found; falling back to the normal base (${baseRef}).\n`,
+            );
+        }
+    }
+
+    const files = analysisBase === baseRef ? packagingFiles : changedFiles(analysisBase, cwd);
+    const diff = diffText(analysisBase, files, cwd);
+    const escalation = escalationReasons(files, changedLineCount(analysisBase, files, cwd));
+    const systemPrompt = buildSystemPrompt(release, baseRef);
     return {
         skills: [...REVIEW_SKILLS],
         files,
-        promptChars: buildSystemPrompt().length + diff.length,
+        analysisBase,
+        ...(release ? { release } : {}),
+        promptChars: systemPrompt.length + diff.length,
         escalation,
         note:
             files.length === 0
                 ? 'No reviewable (non-generated) files changed — the live review would no-op.'
                 : `${files.length} reviewable file(s); live review would send ~${Math.ceil(
-                      (buildSystemPrompt().length + diff.length) / 4,
+                      (systemPrompt.length + diff.length) / 4,
                   )} input tokens.`,
     };
 }
@@ -302,6 +438,10 @@ export function main(argv: string[]): 0 | 2 {
         process.stdout.write(
             `self-review-gate (dry-run — no spend, advisory):\n` +
                 `  skills: ${plan.skills.join(', ')}\n` +
+                (plan.release
+                    ? `  mode:   release (${plan.release.version}; feature range ${plan.release.previousTag}...HEAD; ` +
+                      `packaging diff ${plan.release.packagingFiles.length} file(s))\n`
+                    : '') +
                 `  files:  ${plan.files.length}\n` +
                 `  ${plan.note}\n` +
                 (plan.escalation.length
@@ -341,7 +481,7 @@ export function main(argv: string[]): 0 | 2 {
     // findings returns 2 — an error is not a finding.)
     try {
         const client = new AnthropicClient({ api_key: key });
-        const resp = client.ask(buildSystemPrompt(), diffText(baseRef, plan.files), 4096);
+        const resp = client.ask(buildSystemPrompt(plan.release, baseRef), diffText(plan.analysisBase, plan.files), 4096);
         if (resp.error) {
             process.stdout.write(
                 `::warning::self-review-gate NEUTRAL — model call did not complete (${resp.error}); ` +

package/src/scripts/session_canary_hook.ts

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+/**
+ * Session-canary injection — `session_start` hook.
+ *
+ * Deterministic backstop for the `session-canary` rule. When the consumer has
+ * set `personal.canary_name` in `.agent-settings.yml`, every NEW session gets a
+ * `<session-canary>` context block injected at start (same mechanism as
+ * hot-context: `{"decision":"allow","context":"<block>"}` on stdout; the
+ * dispatcher forwards `context` on session_start so the host adds it to the
+ * session context).
+ *
+ * Why a hook and not just the rule: the canary contract (greet the user by
+ * name at task start; reply-close markers at the end of work replies) is a
+ * liveness signal — the user watches it like a canary in a coal mine, and its
+ * silent disappearance means the context window is degrading. A trigger-routed
+ * rule alone is exactly the kind of surface that is dropped in fresh
+ * conversations (found RED baseline on the reply-close PR-URL contract,
+ * 2026-07-27); the session_start injection makes the contract present in every
+ * new conversation on hook-capable hosts. Copilot (no hook surface) falls back
+ * to the rule alone.
+ *
+ * Gate: `personal.canary_name` non-empty. Missing settings file, missing key,
+ * or empty value → clean no-op (exit 0, no stdout). Never blocks
+ * (fail_closed: false).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { readHookStdin } from "./hooks/hook_stdin.js";
+
+const EXIT_ALLOW = 0;
+
+export const SETTINGS_FILE = ".agent-settings.yml";
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+function _isObject(v: unknown): v is JsonObject {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Minimal line-walker for `personal.canary_name` — no YAML dependency, same
+ * approach as onboarding_gate_hook._read_onboarded. Returns the raw scalar or
+ * null when the section/key is absent.
+ */
+export function read_canary_name(settings_path: string): string | null {
+  let text: string;
+  try {
+    if (!fs.statSync(settings_path).isFile()) {
+      return null;
+    }
+    text = fs.readFileSync(settings_path, "utf-8");
+  } catch {
+    return null;
+  }
+  let in_personal = false;
+  for (const line of text.split(/\r?\n/)) {
+    if (/^personal\s*:\s*(?:#.*)?$/.test(line)) {
+      in_personal = true;
+      continue;
+    }
+    if (in_personal && /^\S/.test(line)) {
+      in_personal = false; // left the personal: block
+    }
+    if (in_personal) {
+      const m = /^\s+canary_name\s*:\s*(.*?)\s*(?:#.*)?$/.exec(line);
+      if (m && m[1] !== undefined) {
+        return m[1].trim();
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * The name is user-owned config, but it lands verbatim in model context —
+ * strip quotes, collapse whitespace, drop markup-significant characters, and
+ * cap the length so a mangled settings file cannot smuggle a paragraph in.
+ */
+export function sanitize_name(raw: string | null): string {
+  if (raw === null) {
+    return "";
+  }
+  let name = raw.trim();
+  if (
+    (name.startsWith('"') && name.endsWith('"')) ||
+    (name.startsWith("'") && name.endsWith("'"))
+  ) {
+    name = name.slice(1, -1);
+  }
+  name = name.replace(/[<>&`]/g, "").replace(/\s+/g, " ").trim();
+  return name.slice(0, 64);
+}
+
+export function build_canary_block(name: string): string {
+  return [
+    `<session-canary settings-key="personal.canary_name">`,
+    `The user has configured a session canary. Two obligations, this whole conversation:`,
+    `1. OPENING CANARY — the first reply of this session, and the first reply of each` +
+      ` NEW task within it, opens by addressing the user by name: "${name}". One natural` +
+      ` mention in the user's language; intermediate replies of the same task do not re-greet.`,
+    `2. CLOSING CANARY — a reply that landed substantial work ends with ONE compact` +
+      ` end-summary, and a PR created or updated this turn puts its raw URL as the` +
+      ` LITERAL LAST LINE (reply-close contract of the direct-answers rule).`,
+    `Purpose: the user watches these markers like a canary in a mine — their silent` +
+      ` disappearance signals context degradation. Never fake continuity: if you notice` +
+      ` you dropped a canary, say so and suggest a fresh session or /agent-handoff.`,
+    `</session-canary>`,
+  ].join("\n");
+}
+
+function _workspaceRoot(envelope: JsonObject): string {
+  const v = envelope["workspace_root"];
+  if (typeof v === "string" && v) {
+    return v;
+  }
+  return process.cwd();
+}
+
+export function main(): number {
+  let envelope: JsonValue = {};
+  try {
+    const raw = _readStdin();
+    envelope = raw.trim() ? (JSON.parse(raw) as JsonValue) : {};
+  } catch {
+    // malformed stdin — still try cwd-based settings below; never block
+  }
+  const env: JsonObject = _isObject(envelope) ? envelope : {};
+
+  // Only session_start carries context-injection semantics; other events no-op.
+  const event = env["event"];
+  if (typeof event === "string" && event !== "" && event !== "session_start") {
+    return EXIT_ALLOW;
+  }
+
+  const root = _workspaceRoot(env);
+  const name = sanitize_name(read_canary_name(path.join(root, SETTINGS_FILE)));
+  if (!name) {
+    return EXIT_ALLOW; // canary not configured — clean no-op
+  }
+
+  process.stdout.write(
+    `${JSON.stringify({
+      decision: "allow",
+      reason: `session-canary: active for "${name}"`,
+      context: build_canary_block(name),
+    })}\n`,
+  );
+  return EXIT_ALLOW;
+}
+
+function _readStdin(): string {
+  return readHookStdin();
+}
+
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+  if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+    return false;
+  }
+  if (process.argv[1] === undefined) {
+    return false;
+  }
+  const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+  if (import.meta.url === argvUrl) {
+    return true;
+  }
+  try {
+    const here = fs.realpathSync(fileURLToPath(import.meta.url));
+    const argv = fs.realpathSync(path.resolve(process.argv[1]));
+    return here === argv;
+  } catch {
+    return false;
+  }
+}
+
+if (_isCliEntry()) {
+  process.exit(main());
+}

package/src/scripts/smoke_quickstart.ts

@@ -78,8 +78,8 @@ function _checkInstallerRuns(tmpdir: string): [number, string | null] {
     ];
     // ADR-020: --project is reserved for maintainers; CI is a maintainer context.
     const env = { ...process.env, AGENT_CONFIG_DEV_MODE: '1' };
-    // Run the installer's `.ts` twin via the repo-local tsx binary (was
-    // `python3 install.py`; the retired Python implementation is deleted).
+    // Run the installer's `.ts` twin via the repo-local tsx binary (the
+    // retired Python implementation is deleted, ADR-200).
     const result = spawnSync(TSX_BIN, cmd, {
         encoding: 'utf-8',
         timeout: 60000,

package/src/scripts/surface_probe_hook.ts

@@ -28,6 +28,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
 import { is_replay_mode } from './hooks/state_io.js';
+import { readHookStdin } from './hooks/hook_stdin.js';
 
 const CHECK_WINDOW_MS = 24 * 60 * 60 * 1000;
 const STATE_REL = ['agents', 'runtime', 'state', 'surface-probe.json'] as const;
@@ -50,13 +51,7 @@ function _package_root(): string {
 }
 
 function _readStdinIfNotTty(): void {
-    try {
-        if (!process.stdin.isTTY) {
-            fs.readFileSync(0, 'utf-8');
-        }
-    } catch {
-        /* ignore */
-    }
+    readHookStdin();
 }
 
 function _exists(p: string): boolean {
@@ -209,7 +204,13 @@ export function main(argv?: string[], opts: ProbeOptions = {}): number {
     }
 }
 
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
 function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+        return false;
+    }
     if (process.argv[1] === undefined) {
         return false;
     }