@event4u/agent-config 9.26.0 → 9.27.0

package/src/scripts/orchestration_backfill.ts

@@ -0,0 +1,354 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * Backfill orchestration telemetry from the host transcript corpus.
+ *
+ * Why this exists (road-to-orchestrator-first-execution Phase 1). Two roadmaps
+ * are blocked on "≥20 orchestration lines in the current month", with the
+ * stated remedy "use the agent on real delegable work". Measured 2026-08-07:
+ * the agent was used on real delegable work **370 times** in this repo over one
+ * month, and `orchestration_record` — a model-carried emit step — captured
+ * exactly **one** of them. The blocker was never a usage problem; it is an
+ * instrumentation defect, and the data it was waiting for is already on disk.
+ *
+ * What this reads. The host writes one JSONL transcript per session under
+ * `~/.claude/projects/<slugified-project-path>/`. An `Agent` dispatch appears
+ * as a `tool_use` block; its result appears as a `toolUseResult` object.
+ *
+ * The coverage limit, which is the point rather than a footnote. Only
+ * SYNCHRONOUS dispatches carry cost: `totalTokens`, `totalDurationMs`,
+ * `usage`. An ASYNCHRONOUS dispatch returns a launch acknowledgement
+ * (`isAsync: true`, `status: "async_launched"`) and its completion never
+ * writes cost back into the parent transcript. So the metric-bearing
+ * population is a strict subset, and this script reports both counts rather
+ * than the flattering one. Emitting 370 lines of which 331 carry a null cost
+ * would inflate n against a gate that counts lines.
+ *
+ * What this deliberately does NOT do. It does not compute a `token_delta`
+ * against an in-session baseline. That counterfactual is not on disk and is
+ * not measured by anything, so synthesising one here and stamping it
+ * `measured` is the exact laundering `orchestration-observed-dispatch-cost`
+ * criterion (2) forbids. The orchestrated side is measured; the baseline is a
+ * downstream decision that must name its own method.
+ *
+ * Read-only. Never mutates a transcript.
+ */
+
+import { readFileSync, readdirSync, existsSync, writeFileSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { homedir } from 'node:os';
+
+/** One dispatch-family. `unclassified` is a real answer, never a guess. */
+export type DispatchFamily =
+    | 'read-only-fanout'
+    | 'ordered-steps'
+    | 'competitive'
+    | 'verdict-judge'
+    | 'unclassified';
+
+/**
+ * One backfilled dispatch.
+ *
+ * PII/leak-exclusion by construction: the host's free-text `description` and
+ * `prompt` are read to CLASSIFY and are then dropped — no field here can carry
+ * free-form content. This is not fastidiousness: the first real run emitted a
+ * historical task description carrying a denylisted external-source name and
+ * tripped `check_no_external_sources`. A type that cannot hold arbitrary text
+ * has no scrubber to fail, which is the same principle
+ * `artifact-engagement-recording` states for telemetry events. Never widen
+ * this with a `description` / `notes` / `payload` field.
+ */
+export interface BackfilledDispatch {
+    session_id: string;
+    tool_use_id: string;
+    timestamp: string | null;
+    subagent_type: string | null;
+    family: DispatchFamily;
+    family_signal: string;
+    resolved_model: string | null;
+    /** Measured orchestrated-side cost. `null` on an async dispatch. */
+    total_tokens: number | null;
+    wall_clock_ms: number | null;
+    tool_use_count: number | null;
+    /** `measured` only when the host recorded the cost; never inferred. */
+    cost_provenance: 'measured' | 'absent';
+    async_launch: boolean;
+}
+
+/**
+ * Slugify a project path the way the host names its transcript directory:
+ * every character outside `[A-Za-z0-9]` becomes `-`.
+ */
+export function transcriptDirFor(projectPath: string, home = homedir()): string {
+    return join(home, '.claude', 'projects', projectPath.replace(/[^A-Za-z0-9]/g, '-'));
+}
+
+/**
+ * Classify a dispatch into a family from OBSERVABLE fields only.
+ *
+ * The council's round-2 finding was that eight dispatch templates were being
+ * treated as one hypothesis. Family is therefore carried per line. Where no
+ * enumerated signal matches, the answer is `unclassified` — the same
+ * discipline `classifyTask` applies when no delegable signal matches. A
+ * classifier that always produces a family would make the per-family split
+ * meaningless.
+ */
+export function classifyFamily(
+    subagentType: string | null,
+    description: string | null,
+    prompt: string | null,
+): { family: DispatchFamily; signal: string } {
+    const hay = `${description ?? ''}\n${prompt ?? ''}`.toLowerCase();
+
+    // Verdict/judge first — it is the narrowest and can otherwise be swallowed
+    // by the read-only signal, since most verdict passes are also read-only.
+    if (subagentType === 'production-validator') {
+        return { family: 'verdict-judge', signal: 'subagent_type=production-validator' };
+    }
+    if (/\b(verify|verdict|judge|adjudicat|audit this|review this|acceptance criterion)\b/.test(hay)) {
+        return { family: 'verdict-judge', signal: 'verdict-shaped verb in description/prompt' };
+    }
+
+    if (subagentType === 'Explore') {
+        return { family: 'read-only-fanout', signal: 'subagent_type=Explore' };
+    }
+    if (/\b(read-only|do not edit|never edit|investigation only|map |inventory|locate)\b/.test(hay)) {
+        return { family: 'read-only-fanout', signal: 'read-only declaration in prompt' };
+    }
+
+    if (/\b(step \d|then |after (the )?previous|in order|sequentially|depends on step)\b/.test(hay)) {
+        return { family: 'ordered-steps', signal: 'ordering language in prompt' };
+    }
+
+    if (/\b(variant|competing|alternative approach|candidate [ab]|independently propose)\b/.test(hay)) {
+        return { family: 'competitive', signal: 'competitive framing in prompt' };
+    }
+
+    return { family: 'unclassified', signal: 'no enumerated family signal matched' };
+}
+
+interface Extraction {
+    dispatches: BackfilledDispatch[];
+    sessions_scanned: number;
+    unparseable_lines: number;
+}
+
+/** Walk one project's transcript corpus and pair each `Agent` tool_use with its result. */
+export function extract(dir: string): Extraction {
+    if (!existsSync(dir)) {
+        return { dispatches: [], sessions_scanned: 0, unparseable_lines: 0 };
+    }
+    const files = readdirSync(dir).filter((f) => f.endsWith('.jsonl'));
+    const dispatches: BackfilledDispatch[] = [];
+    let unparseable = 0;
+
+    for (const file of files) {
+        const sessionId = file.replace(/\.jsonl$/, '');
+        // tool_use_id → the dispatch we are still waiting on a result for.
+        const pending = new Map<string, Partial<BackfilledDispatch> & { prompt: string | null; description: string | null }>();
+        const emitted = new Map<string, BackfilledDispatch>();
+
+        for (const line of readFileSync(join(dir, file), 'utf8').split('\n')) {
+            if (line.trim() === '') continue;
+            let obj: Record<string, unknown>;
+            try {
+                obj = JSON.parse(line) as Record<string, unknown>;
+            } catch {
+                unparseable += 1;
+                continue;
+            }
+
+            const message = obj.message as Record<string, unknown> | undefined;
+            const content = message?.content;
+            if (Array.isArray(content)) {
+                for (const block of content) {
+                    const b = block as Record<string, unknown>;
+                    if (b.type !== 'tool_use' || b.name !== 'Agent') continue;
+                    const input = (b.input ?? {}) as Record<string, unknown>;
+                    const id = String(b.id ?? '');
+                    if (id === '') continue;
+                    pending.set(id, {
+                        session_id: sessionId,
+                        tool_use_id: id,
+                        timestamp: typeof obj.timestamp === 'string' ? obj.timestamp : null,
+                        subagent_type: typeof input.subagent_type === 'string' ? input.subagent_type : null,
+                        description: typeof input.description === 'string' ? input.description : null,
+                        prompt: typeof input.prompt === 'string' ? input.prompt : null,
+                    });
+                }
+            }
+
+            const result = obj.toolUseResult as Record<string, unknown> | undefined;
+            if (!result || typeof result !== 'object') continue;
+            // The result carries no tool_use_id of its own; the host pairs it via
+            // the enclosing user message's tool_result block.
+            let resultId: string | null = null;
+            if (Array.isArray(content)) {
+                for (const block of content) {
+                    const b = block as Record<string, unknown>;
+                    if (b.type === 'tool_result' && typeof b.tool_use_id === 'string') {
+                        resultId = b.tool_use_id;
+                    }
+                }
+            }
+            if (resultId === null || !pending.has(resultId)) continue;
+            const head = pending.get(resultId)!;
+            pending.delete(resultId);
+
+            const totalTokens = typeof result.totalTokens === 'number' ? result.totalTokens : null;
+            const { family, signal } = classifyFamily(
+                head.subagent_type ?? null,
+                head.description ?? null,
+                head.prompt,
+            );
+
+            emitted.set(resultId, {
+                session_id: sessionId,
+                tool_use_id: resultId,
+                timestamp: head.timestamp ?? null,
+                subagent_type: head.subagent_type ?? null,
+                family,
+                family_signal: signal,
+                resolved_model: typeof result.resolvedModel === 'string' ? result.resolvedModel : null,
+                total_tokens: totalTokens,
+                wall_clock_ms: typeof result.totalDurationMs === 'number' ? result.totalDurationMs : null,
+                tool_use_count: typeof result.totalToolUseCount === 'number' ? result.totalToolUseCount : null,
+                cost_provenance: totalTokens === null ? 'absent' : 'measured',
+                async_launch: result.isAsync === true,
+            });
+        }
+
+        dispatches.push(...emitted.values());
+        // A dispatch whose result never landed in this transcript (session ended
+        // mid-flight) is reported as a gap rather than dropped silently.
+        for (const [id, head] of pending) {
+            const { family, signal } = classifyFamily(
+                head.subagent_type ?? null,
+                head.description ?? null,
+                head.prompt,
+            );
+            dispatches.push({
+                session_id: sessionId,
+                tool_use_id: id,
+                timestamp: head.timestamp ?? null,
+                subagent_type: head.subagent_type ?? null,
+                family,
+                family_signal: signal,
+                resolved_model: null,
+                total_tokens: null,
+                wall_clock_ms: null,
+                tool_use_count: null,
+                cost_provenance: 'absent',
+                async_launch: false,
+            });
+        }
+    }
+
+    return { dispatches, sessions_scanned: files.length, unparseable_lines: unparseable };
+}
+
+/**
+ * The shape that actually gets written to disk.
+ *
+ * `tool_use_id` is pairing plumbing: it exists to match a dispatch to its
+ * result during extraction and has no analytical role afterwards. It is
+ * dropped at the TYPE level rather than scrubbed at write time, because the
+ * host ids are high-entropy opaque tokens and `check_secret_leak` flags them
+ * as candidate credentials — correctly, in the sense that it cannot know they
+ * are not. Emitting a field only to allow-list it downstream is the worse
+ * trade: the artifact does not need it.
+ */
+export type EmittedDispatch = Omit<BackfilledDispatch, 'tool_use_id'>;
+
+/** Project an extracted dispatch onto the emitted shape. */
+export function toEmitted(d: BackfilledDispatch): EmittedDispatch {
+    const { tool_use_id: _pairingKey, ...rest } = d;
+    return rest;
+}
+
+/** Per-family roll-up. Medians, never means — one 530k outlier should not carry a family. */
+export function summarize(dispatches: BackfilledDispatch[]): Record<string, unknown> {
+    const byFamily = new Map<string, number[]>();
+    for (const d of dispatches) {
+        if (d.cost_provenance !== 'measured' || d.total_tokens === null) continue;
+        const bucket = byFamily.get(d.family) ?? [];
+        bucket.push(d.total_tokens);
+        byFamily.set(d.family, bucket);
+    }
+    const families: Record<string, unknown> = {};
+    for (const [family, tokens] of byFamily) {
+        tokens.sort((a, b) => a - b);
+        families[family] = {
+            n: tokens.length,
+            // criterion (1): n<5 is UNDERPOWERED and is never merged to reach n.
+            power: tokens.length < 5 ? 'UNDERPOWERED' : 'reportable',
+            median_tokens: tokens[Math.floor(tokens.length / 2)],
+            min_tokens: tokens[0],
+            max_tokens: tokens[tokens.length - 1],
+            sum_tokens: tokens.reduce((a, b) => a + b, 0),
+        };
+    }
+    const measured = dispatches.filter((d) => d.cost_provenance === 'measured').length;
+    return {
+        dispatches_total: dispatches.length,
+        dispatches_with_measured_cost: measured,
+        dispatches_without_cost: dispatches.length - measured,
+        async_launches: dispatches.filter((d) => d.async_launch).length,
+        cost_coverage_ratio: dispatches.length === 0 ? 0 : Number((measured / dispatches.length).toFixed(4)),
+        families,
+        models: dispatches
+            .filter((d) => d.cost_provenance === 'measured')
+            .reduce<Record<string, number>>((acc, d) => {
+                const key = d.resolved_model ?? 'unknown';
+                acc[key] = (acc[key] ?? 0) + 1;
+                return acc;
+            }, {}),
+        baseline_note:
+            'No in-session counterfactual exists on disk. token_delta is NOT computed here; ' +
+            'any downstream comparison must name its own baseline method and stamp it estimated.',
+    };
+}
+
+function main(argv: string[]): number {
+    const projectArg = argv.indexOf('--project');
+    const project =
+        projectArg >= 0 && argv[projectArg + 1] !== undefined ? argv[projectArg + 1]! : process.cwd();
+    const outArg = argv.indexOf('--out');
+    const dir = transcriptDirFor(project);
+
+    if (!existsSync(dir)) {
+        process.stderr.write(`orchestration_backfill: no transcript corpus at ${dir}\n`);
+        return 1;
+    }
+
+    const { dispatches, sessions_scanned, unparseable_lines } = extract(dir);
+    const summary = summarize(dispatches);
+    // Emit the corpus identity, never the absolute path: the transcript
+    // directory is rooted at the operator's home and a committed report
+    // carrying it leaks an identity-revealing local path for no analytical
+    // gain (the basename already identifies which corpus was read).
+    const report = {
+        schema_version: 1,
+        source_corpus: basename(dir),
+        sessions_scanned,
+        unparseable_lines,
+        ...summary,
+    };
+
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+
+    if (outArg >= 0 && argv[outArg + 1] !== undefined) {
+        const lines = dispatches
+            .filter((d) => d.cost_provenance === 'measured')
+            .map((d) => JSON.stringify({ input_kind: 'orchestration', orchestration: toEmitted(d) }))
+            .join('\n');
+        writeFileSync(argv[outArg + 1]!, lines === '' ? '' : `${lines}\n`, 'utf8');
+        process.stderr.write(
+            `orchestration_backfill: wrote ${summary.dispatches_with_measured_cost} measured line(s) to ${argv[outArg + 1]}\n`,
+        );
+    }
+    return 0;
+}
+
+if (process.argv[1] !== undefined && process.argv[1].includes('orchestration_backfill')) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/release.ts

@@ -700,13 +700,84 @@ export function _failed_checks_report(names: readonly string[]): string {
     return lines.join('\n');
 }
 
+/** Rounds of re-watching before an absent required check is called absent. */
+const _NO_CHECKS_ROUNDS = 10;
+/** Delay between those rounds — 10 × 60 s ≈ 10 minutes of tolerance. */
+const _NO_CHECKS_DELAY_MS = 60_000;
+
 /**
- * Watch PR checks and tolerate the 'no checks' case.
+ * Required status-check contexts for a branch, parsed from
+ * `gh api repos/{owner}/{repo}/rules/branches/{branch}`.
+ *
+ * That endpoint is the one that answers the question here: this repo protects
+ * `main` with a RULESET, and the classic `/branches/main/protection` API
+ * answers "Branch not protected" for it — so a check built on the classic
+ * endpoint would conclude "no required checks" and wave everything through.
+ *
+ * Any parse or shape surprise yields [] — the caller then behaves exactly as
+ * it did before this function existed.
+ */
+export function _required_contexts_from_rules(json: string): string[] {
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(json);
+    } catch {
+        return [];
+    }
+    if (!Array.isArray(parsed)) return [];
+    const out: string[] = [];
+    for (const rule of parsed) {
+        const r = rule as { type?: unknown; parameters?: { required_status_checks?: unknown } };
+        if (r.type !== 'required_status_checks') continue;
+        const checks = r.parameters?.required_status_checks;
+        if (!Array.isArray(checks)) continue;
+        for (const c of checks) {
+            const ctx = (c as { context?: unknown }).context;
+            if (typeof ctx === 'string' && ctx !== '') out.push(ctx);
+        }
+    }
+    return out;
+}
+
+export type NoChecksAction = 'retry' | 'accept' | 'die';
+
+/**
+ * What to do when `gh pr checks` reports no checks at all.
+ *
+ * The old code had one answer — accept — for two situations it could not tell
+ * apart: a repo that configures no required checks (nothing will ever arrive,
+ * accepting is correct) and a repo whose checks have simply not been
+ * dispatched yet (accepting merges, tags and publishes unvalidated).
+ *
+ * The branch's own protection rules separate them. Required contexts declared
+ * ⇒ something IS expected, so absence means not-yet, and the answer is to wait
+ * and finally to refuse. None declared ⇒ the pre-existing tolerance stands.
+ */
+export function _no_checks_action(
+    required: readonly string[],
+    round: number,
+    maxRounds: number = _NO_CHECKS_ROUNDS,
+): NoChecksAction {
+    if (required.length === 0) return 'accept';
+    return round < maxRounds ? 'retry' : 'die';
+}
+
+/**
+ * Watch PR checks and tolerate the 'no checks' case ONLY where it is tolerable.
  *
  * `gh pr checks --watch` exits 1 both on real failures and when no checks are
- * reported at all (no workflow triggered, no required checks configured in
- * branch protection). The latter must not block the release — we warn and
- * continue. Real failures still die.
+ * reported at all. Real failures still die.
+ *
+ * Measured 2026-08-06/07: during a critical GitHub Actions incident
+ * (15:22–02:04 UTC, webhook triggers throttled from 20:34) `pull_request`
+ * events were delivered 15–30 minutes late. The five-second grace period below
+ * expires long before that, so the old unconditional accept would have tagged
+ * `main` and published to npm without a single check having run. It did not
+ * only because `main` happened to be independently green.
+ *
+ * So the tolerance is now conditional on the branch declaring no required
+ * checks. Where it declares some, absence is treated as latency: re-watch, and
+ * refuse rather than release blind.
  *
  * A short grace period gives GitHub time to register workflow runs on a
  * freshly-pushed branch.
@@ -721,41 +792,76 @@ function watch_pr_checks(branch: string): void {
             // busy-wait stand-in for time.sleep(5) without an event-loop yield.
         }
     }
-    // The branch is passed explicitly — `gh` inferring the PR from HEAD
-    // resolved to `main` mid-run once (2026-08-03, 9.16.0 resume) and the
-    // whole release died on "no pull requests found for branch main".
-    const proc = run(['gh', 'pr', 'checks', branch, '--watch'], {
-        check: false,
-        capture: true,
-    });
-    const output = ((proc.stdout || '') + (proc.stderr || '')).trim();
-    const returncode = proc.returncode;
-    if (returncode === 0) {
+    // Rounds exist only for the no-checks-yet case below; every other outcome
+    // returns or dies on the first pass, exactly as before.
+    for (let round = 0; ; round++) {
+        // The branch is passed explicitly — `gh` inferring the PR from HEAD
+        // resolved to `main` mid-run once (2026-08-03, 9.16.0 resume) and the
+        // whole release died on "no pull requests found for branch main".
+        const proc = run(['gh', 'pr', 'checks', branch, '--watch'], {
+            check: false,
+            capture: true,
+        });
+        const output = ((proc.stdout || '') + (proc.stderr || '')).trim();
+        const returncode = proc.returncode;
+        if (returncode === 0) {
+            if (output) {
+                process.stdout.write(output + '\n');
+            }
+            return;
+        }
+        if (output.toLowerCase().includes('no checks reported')) {
+            const rules = run(
+                ['gh', 'api', `repos/{owner}/{repo}/rules/branches/${MAIN_BRANCH}`],
+                { check: false, capture: true },
+            );
+            const required = _required_contexts_from_rules(rules.stdout ?? '');
+            const action = _no_checks_action(required, round, _NO_CHECKS_ROUNDS);
+
+            if (action === 'accept') {
+                process.stdout.write(`⚠️  ${output}\n`);
+                process.stdout.write(
+                    '   Continuing without check validation — configure required ' +
+                        'checks in branch protection to enforce this gate.\n',
+                );
+                return;
+            }
+            if (action === 'retry') {
+                process.stdout.write(
+                    `⏳  no checks reported yet, but ${MAIN_BRANCH} requires ` +
+                        `${String(required.length)} (${required.join(', ')}) — ` +
+                        `waiting (${String(round + 1)}/${String(_NO_CHECKS_ROUNDS)})\n`,
+                );
+                if (_exec_override === null) {
+                    const until = Date.now() + _NO_CHECKS_DELAY_MS;
+                    while (Date.now() < until) {
+                        // blocking wait, same shape as the grace period above
+                    }
+                }
+                continue;
+            }
+            die(
+                `no checks reported for ${branch} after ` +
+                    `${String(_NO_CHECKS_ROUNDS)} rounds, but ${MAIN_BRANCH} requires ` +
+                    `${required.join(', ')}. Refusing to merge, tag and publish ` +
+                    'unvalidated — GitHub may be delaying event delivery (check ' +
+                    'githubstatus.com). Re-run with `task release -- --resume --yes` ' +
+                    'once the checks appear.',
+            );
+        }
         if (output) {
-            process.stdout.write(output + '\n');
+            process.stderr.write(output + '\n');
         }
-        return;
-    }
-    if (output.toLowerCase().includes('no checks reported')) {
-        process.stdout.write(`⚠️  ${output}\n`);
-        process.stdout.write(
-            '   Continuing without check validation — configure required ' +
-                'checks in branch protection to enforce this gate.\n',
-        );
-        return;
-    }
-    if (output) {
-        process.stderr.write(output + '\n');
-    }
-    const summary = run(['gh', 'pr', 'checks', branch, '--json', 'name,bucket'], {
-        check: false,
-        capture: true,
-    });
-    const report = _failed_checks_report(_failed_check_names(summary.stdout ?? ''));
-    if (report) {
-        process.stderr.write(report + '\n');
+        const summary = run(['gh', 'pr', 'checks', branch, '--json', 'name,bucket'], {
+            check: false,
+            capture: true,
+        });
+        const report = _failed_checks_report(_failed_check_names(summary.stdout ?? ''));
+        if (report) {
+            process.stderr.write(report + '\n');
+        }
+        die(`PR checks failed (exit ${returncode})`);
     }
-    die(`PR checks failed (exit ${returncode})`);
 }
 
 /**

package/src/scripts/schemas/rule.schema.json

@@ -154,6 +154,11 @@
       },
       "description": "What mechanically enforces this rule. `validator:<script>` and `test:<path>` must resolve on disk AND be wired into a taskfile, workflow, or the hook manifest — a script that exists but runs nowhere resolves to unwired, not covered. `hook:<name>` must be registered in hook_manifest.yaml with fail_closed: true; a hook that never blocks is `observer:`, not `validator:`. `none` is legal and counted — an honest gap beats a false claim. Resolved, not trusted, by check_enforcement_coverage.ts."
     },
+    "obligation_frequency": {
+      "type": "string",
+      "enum": ["per-edit", "per-turn", "per-task", "per-session", "per-event", "per-commit", "per-file-write", "none"],
+      "description": "How often this rule's obligation comes due — the question `enforced_by` does not answer. `enforced_by` asks *does something carry this*; a carrier can be wired, reachable and firing and still fire in the wrong slot (session-canary: a per-task obligation carried by a session_start hook, measured dropped on ~13 of 15 task starts while counting as enforced). Joined against the carrier's per-slot-and-platform firing frequency by check_enforcement_coverage.ts. The value set is a FOREST, not a chain — three roots that never cover one another: lifecycle (`per-turn` > `per-task` > `per-session`), repository-write (`per-commit`, `per-file-write`), and external-event (`per-event`). `per-edit` is a fourth, incomparable-to-`per-turn` case: pre/post_tool_use fire per tool call, so a conversational turn with no tool call fires them zero times. `none` = no recurring obligation (a pointer or reference rule). Required on every non-kernel rule by validate_frontmatter.ts; the nine kernel rules are exempt because block_kernel_rule_writes.ts denies agent writes to them, and that exemption is derived from _lib/kernel_rules.ts so it closes itself the moment a rule leaves the kernel."
+    },
     "trust": {
       "type": "object",
       "additionalProperties": false,

package/src/scripts/session_canary_hook.ts

@@ -184,6 +184,29 @@ export function sanitize_name(raw: string | null): string {
   return name.slice(0, 64);
 }
 
+/**
+ * The per-turn reminder — one line, deliberately not the full contract.
+ *
+ * The obligation is per TASK; the injection was per SESSION. No host has a
+ * per-task slot (Cline maps TaskStart/TaskResume onto `session_start`; Claude
+ * Code has no task event), so the reachable covering period is per-turn, which
+ * is a strict superset. The measured consequence of leaving it at session scope:
+ * a 30-session audit found the opening canary dropped on ~13 of 15 task starts.
+ *
+ * Re-injecting the ~800-char contract every turn would buy that coverage at
+ * roughly 40× the tokens over a long session, so the full block stays at
+ * `session_start` and this line carries the beat. Over-firing a greeting is a
+ * visible, cheap failure; under-firing is the silent one being fixed.
+ */
+export function build_canary_reminder(name: string): string {
+    return (
+        `<session-canary-beat>Canary active for "${name}": if this turn STARTS A NEW TASK,` +
+        ` open by addressing them by name. Same task as the last turn → do not re-greet.` +
+        ` A reply that lands work still ends with ONE summary (PR URL last).` +
+        `</session-canary-beat>`
+    );
+}
+
 export function build_canary_block(name: string): string {
   return [
     `<session-canary settings-key="personal.canary_name">`,
@@ -219,9 +242,15 @@ export function main(): number {
   }
   const env: JsonObject = _isObject(envelope) ? envelope : {};
 
-  // Only session_start carries context-injection semantics; other events no-op.
+  // Two injection points, two payloads. `session_start` carries the full
+  // contract once; `user_prompt_submit` carries the one-line beat, because the
+  // obligation is per task and session scope cannot reach it. Every other event
+  // no-ops — notably `stop`, where re-injecting would fire after the reply the
+  // reminder was meant to shape.
   const event = env["event"];
-  if (typeof event === "string" && event !== "" && event !== "session_start") {
+  const slot =
+    typeof event === "string" && event !== "" ? event : "session_start";
+  if (slot !== "session_start" && slot !== "user_prompt_submit") {
     return EXIT_ALLOW;
   }
 
@@ -235,7 +264,10 @@ export function main(): number {
     `${JSON.stringify({
       decision: "allow",
       reason: `session-canary: active for "${name}" (${layer})`,
-      context: build_canary_block(name),
+      context:
+        slot === "session_start"
+          ? build_canary_block(name)
+          : build_canary_reminder(name),
     })}\n`,
   );
   return EXIT_ALLOW;