pi-dev-team 0.2.0

package/extensions/dev-team/lib/usage-state.ts

@@ -0,0 +1,116 @@
+/**
+ * The state machine behind the /dev-team usage overlay: which scope and view are shown and how the
+ * this-month load is going. Pure: `reduce` maps a state and an action (a key, or news from the load)
+ * to the next state plus the effects the view must carry out (start or cancel the load, close), so
+ * every rule is testable without pi or a terminal. Mapping raw terminal input to a UsageKey lives
+ * here too, as it is the machine's other input.
+ */
+import { Key, type KeyId, matchesKey } from "@earendil-works/pi-tui";
+
+export type Scope = "session" | "month";
+export type View = "model" | "provider" | "agent";
+
+/**
+ * The this-month history load. It outlives the scope: "ready" is kept when the user goes back to this
+ * session, so pressing `s` again shows the loaded month at once. A cancelled or failed load is "idle"
+ * again, so `s` restarts it. In this-session scope the load is therefore only ever idle or ready.
+ */
+export type LoadState =
+	| { kind: "idle" }
+	| { kind: "loading"; progress?: { done: number; total: number } }
+	| { kind: "ready" }
+	| { kind: "error"; reason: string };
+
+export interface UsageState {
+	scope: Scope;
+	view: View;
+	load: LoadState;
+}
+
+/** What a key press means, independent of which key produced it. */
+export type UsageKey = "next-view" | "previous-view" | "toggle-scope" | "close";
+
+export type UsageAction =
+	| { type: "key"; key: UsageKey }
+	| { type: "progress"; done: number; total: number }
+	| { type: "loaded" }
+	| { type: "failed"; reason: string };
+
+/** What the view must do besides re-render. */
+export type UsageEffect = "start-load" | "cancel-load" | "close";
+
+export interface Transition {
+	state: UsageState;
+	effects: UsageEffect[];
+}
+
+/** Left to right as Tab walks them. */
+const VIEWS: readonly View[] = ["model", "provider", "agent"];
+
+const LOADING: LoadState = { kind: "loading" };
+const IDLE: LoadState = { kind: "idle" };
+
+/** The state a freshly opened overlay starts in: By model, with the month's load started when it opens on the month. */
+export function openUsage(scope: Scope): Transition {
+	if (scope === "month") return { state: { scope, view: "model", load: LOADING }, effects: ["start-load"] };
+	return { state: { scope, view: "model", load: IDLE }, effects: [] };
+}
+
+function stepView(state: UsageState, step: number): Transition {
+	const next = VIEWS[(VIEWS.indexOf(state.view) + step + VIEWS.length) % VIEWS.length];
+	return { state: { ...state, view: next }, effects: [] };
+}
+
+/** `s`: this session to this month (loading it unless already loaded), and back (cancelling a load still running). */
+function toggleScope(state: UsageState): Transition {
+	if (state.scope === "session") {
+		if (state.load.kind === "ready") return { state: { ...state, scope: "month" }, effects: [] };
+		return { state: { ...state, scope: "month", load: LOADING }, effects: ["start-load"] };
+	}
+	const cancelling = state.load.kind === "loading";
+	const load = state.load.kind === "ready" ? state.load : IDLE;
+	return { state: { ...state, scope: "session", load }, effects: cancelling ? ["cancel-load"] : [] };
+}
+
+function pressKey(state: UsageState, key: UsageKey): Transition {
+	switch (key) {
+		case "next-view":
+			return stepView(state, 1);
+		case "previous-view":
+			return stepView(state, -1);
+		case "toggle-scope":
+			return toggleScope(state);
+		case "close":
+			return { state, effects: state.load.kind === "loading" ? ["cancel-load", "close"] : ["close"] };
+	}
+}
+
+/** News about the load only counts while one is running: a late event from a cancelled load is dropped. */
+function loadEvent(state: UsageState, action: Exclude<UsageAction, { type: "key" }>): Transition {
+	if (state.load.kind !== "loading") return { state, effects: [] };
+	switch (action.type) {
+		case "progress":
+			return { state: { ...state, load: { kind: "loading", progress: { done: action.done, total: action.total } } }, effects: [] };
+		case "loaded":
+			return { state: { ...state, load: { kind: "ready" } }, effects: [] };
+		case "failed":
+			return { state: { ...state, load: { kind: "error", reason: action.reason } }, effects: [] };
+	}
+}
+
+export function reduce(state: UsageState, action: UsageAction): Transition {
+	return action.type === "key" ? pressKey(state, action.key) : loadEvent(state, action);
+}
+
+/** Letters match in either case (`s` and `S`); Shift+Tab is its own key, so it steps back. */
+const KEY_TABLE: readonly { key: UsageKey; ids: readonly KeyId[] }[] = [
+	{ key: "next-view", ids: [Key.tab] },
+	{ key: "previous-view", ids: [Key.shift("tab")] },
+	{ key: "toggle-scope", ids: ["s", Key.shift("s")] },
+	{ key: "close", ids: [Key.escape, "q", Key.shift("q"), Key.ctrl("c")] },
+];
+
+/** The action a chunk of terminal input stands for, or undefined for any other key. */
+export function usageKeyFor(data: string): UsageKey | undefined {
+	return KEY_TABLE.find(({ ids }) => ids.some((id) => matchesKey(data, id)))?.key;
+}

package/extensions/dev-team/lib/usage-text.ts

@@ -0,0 +1,159 @@
+/**
+ * The plain-text usage summary for /dev-team usage when no overlay can be shown (print mode, RPC),
+ * and the wording both it and the overlay (usage-render.ts) use: scope names, view titles, header
+ * pieces, empty-state, failure and footnote sentences. Keeping the sentences here is what keeps the
+ * two presentations saying the same thing.
+ */
+import { formatAiCredits, formatCredits, hasVisibleCredits, usageMonthStart } from "./ai-credits.ts";
+import {
+	formatShare,
+	formatTokens,
+	formatUsd,
+	hasUsage,
+	type MonthSnapshot,
+	type SpendAmounts,
+	THREAD_ORDER,
+	type UsageBreakdown,
+	type UsageRow,
+} from "./usage-breakdown.ts";
+import type { BarChartOptions, ChartFormat } from "./usage-chart.ts";
+import { toSpacedSingleLine, toSingleLine } from "./terminal-text.ts";
+import type { Scope, View } from "./usage-state.ts";
+
+export const SEPARATOR = " · ";
+export const SCOPE_TITLE: Record<Scope, string> = { session: "This session", month: "This month" };
+export const SCOPE_NOUN: Record<Scope, string> = { session: "this session", month: "this month" };
+export const VIEW_TITLE: Record<View, string> = { model: "By model", provider: "By provider", agent: "By agent" };
+/** Joins an agent and its provider in an agent row's label. */
+export const AGENT_PROVIDER_SEPARATOR = " · ";
+/** The chart area's text while this month's files are read; the overlay appends the progress. */
+export const READING_SESSIONS = "Reading sessions…";
+
+/** "in this session", "this month": how a sentence refers to the scope. */
+export const scopePhrase = (scope: Scope) => (scope === "session" ? "in this session" : "this month");
+
+const monthDay = (date: Date) => date.toLocaleDateString("en-US", { month: "short", day: "numeric", timeZone: "UTC" });
+
+/** "This session", or "This month (Oct 1 – Oct 4)": the month's UTC dates, 1st to `now`. */
+export function scopeHeading(scope: Scope, now: Date): string {
+	if (scope === "session") return SCOPE_TITLE.session;
+	return `${SCOPE_TITLE.month} (${monthDay(usageMonthStart(now))} – ${monthDay(now)})`;
+}
+
+/** "as of 14:05": local time, so it reads against the user's own clock. */
+export const asOfLabel = (date: Date) => `as of ${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}`;
+
+/** A row's AI credits in a column: "210 cr", or "" when Copilot served none of it. */
+export const formatCreditsCell = (credits: number) => (hasVisibleCredits(credits) ? `${formatCredits(credits)} cr` : "");
+
+/** How the chart and the summary write each amount. */
+export const CHART_FORMAT: ChartFormat = { usd: formatUsd, credits: formatCreditsCell, tokens: formatTokens, share: formatShare };
+
+/**
+ * The optional columns a view's rows want, for the overlay's chart and the text summary alike: AI
+ * credits when any row has some, tokens when any row cost nothing (so a free model still says what it
+ * used). Judged over every row, before the chart folds any into "other".
+ */
+export function wantedColumns(rows: readonly UsageRow[]): BarChartOptions["wantedColumns"] {
+	return { credits: rows.some((r) => hasVisibleCredits(r.credits)), tokens: rows.some((r) => !(r.usd > 0)) };
+}
+
+/** The total as header parts: "$4.20", then "312 AI credits" when Copilot served any of it. USD is always first. */
+export function totalHeaderParts(total: SpendAmounts): string[] {
+	return [formatUsd(total.usd), ...(hasVisibleCredits(total.credits) ? [formatAiCredits(total.credits)] : [])];
+}
+
+/** The ranked rows of a view; an agent row is labelled "agent · provider". */
+export function viewRows(view: View, breakdown: UsageBreakdown): UsageRow[] {
+	if (view === "model") return breakdown.byModel;
+	if (view === "provider") return breakdown.byProvider;
+	return breakdown.byAgent.map((row) => ({ ...row, label: `${row.label}${AGENT_PROVIDER_SEPARATOR}${row.provider}` }));
+}
+
+/** One split of the total: its parts in drawing order, each with its USD and share of the total. */
+export interface SplitSection {
+	title: "Providers" | "Threads";
+	/** How the overlay's legend names a part's amount. */
+	legend: "share" | "usd";
+	parts: { label: string; usd: number; share: number }[];
+}
+
+/**
+ * The splits both presentations show. Providers: only when two or more have a cost, the paid ones in
+ * rank order. Threads: always main, subagents, overhead, in that order; a thread that spent nothing
+ * stays with 0 so it keeps its place and its glyph. None when nothing cost anything.
+ */
+export function splitSections(breakdown: UsageBreakdown): SplitSection[] {
+	const total = breakdown.total.usd;
+	if (!(total > 0)) return [];
+	const part = (label: string, usd: number) => ({ label, usd, share: usd / total });
+	const paidProviders = breakdown.byProvider.filter((r) => r.usd > 0);
+	const providers: SplitSection[] = paidProviders.length > 1 ? [{ title: "Providers", legend: "share", parts: paidProviders.map((r) => part(r.label, r.usd)) }] : [];
+	const threadUsd = new Map(breakdown.byThread.map((r) => [r.label, r.usd]));
+	return [...providers, { title: "Threads", legend: "usd", parts: THREAD_ORDER.map((label) => part(label, threadUsd.get(label) ?? 0)) }];
+}
+
+export const emptyUsageMessage = (scope: Scope) => `No usage ${scopePhrase(scope)}`;
+export const noSubagentUsageMessage = (scope: Scope) => `No subagent usage ${scopePhrase(scope)}`;
+
+/** Appended to the empty session message: this month may have spend even when this session has none. */
+export const pressSHint = (scope: Scope) => (scope === "session" ? " — press s for this month" : "");
+
+/** The reason is an error's message and may carry escape sequences, control characters or newlines: sequences go, each run of controls becomes one space. */
+export const loadFailedMessage = (reason: string) => `Could not load history: ${toSpacedSingleLine(reason)}`;
+
+/** The text of whatever a load rejected with. */
+export const errorReason = (err: unknown): string => (err instanceof Error ? err.message : String(err));
+
+/** The footnote for session files that could not be read, or undefined when every file was. */
+export function unreadableFilesNote(unreadable: number): string | undefined {
+	return unreadable > 0 ? `${unreadable} session ${unreadable === 1 ? "file" : "files"} could not be read` : undefined;
+}
+
+export interface UsageSummaryInput {
+	scope: Scope;
+	breakdown: UsageBreakdown;
+	now: Date;
+	/** Present for this month: how the load went. */
+	month?: Omit<MonthSnapshot, "breakdown">;
+}
+
+/** Rows as aligned "  label  usd  credits  tokens  share" lines, with the columns wantedColumns() asks for. */
+function rankedLines(rows: readonly UsageRow[]): string[] {
+	const columns = wantedColumns(rows);
+	const cells = rows.map((r) => [
+		toSingleLine(r.label),
+		CHART_FORMAT.usd(r.usd),
+		...(columns.credits ? [CHART_FORMAT.credits(r.credits)] : []),
+		...(columns.tokens ? [CHART_FORMAT.tokens(r.tokens)] : []),
+		CHART_FORMAT.share(r.share),
+	]);
+	const widths = cells[0].map((_, column) => Math.max(...cells.map((row) => row[column].length)));
+	return cells.map((row) => `  ${row.map((cell, column) => (column === 0 ? cell.padEnd(widths[column]) : cell.padStart(widths[column]))).join("  ")}`);
+}
+
+/** "Providers  github-copilot $3.12 74.3% · openai $1.08 25.7%": the parts that spent something. */
+function splitLine({ title, parts }: SplitSection): string {
+	const spent = parts.filter((p) => p.usd > 0);
+	return `${title}  ${spent.map((p) => `${toSingleLine(p.label)} ${formatUsd(p.usd)} ${formatShare(p.share)}`).join(SEPARATOR)}`;
+}
+
+/** Header, the provider and thread splits, then models, providers and agents ranked; or the empty-state sentence. Either way the unreadable-files note ends it, as in the overlay. */
+export function usageSummary({ scope, breakdown, now, month }: UsageSummaryInput): string {
+	const note = unreadableFilesNote(month?.unreadable ?? 0);
+	const noteLines = note ? ["", note] : [];
+	if (!hasUsage(breakdown.total)) return [emptyUsageMessage(scope), ...noteLines].join("\n");
+	const header = [scopeHeading(scope, now), ...totalHeaderParts(breakdown.total), ...(month ? [asOfLabel(month.loadedAt)] : [])].join(SEPARATOR);
+	const section = (view: View) => {
+		const rows = viewRows(view, breakdown);
+		return ["", VIEW_TITLE[view], ...(rows.length ? rankedLines(rows) : [`  ${noSubagentUsageMessage(scope)}`])];
+	};
+	return [
+		header,
+		...splitSections(breakdown).map(splitLine),
+		...section("model"),
+		...section("provider"),
+		...section("agent"),
+		...noteLines,
+	].join("\n");
+}

package/extensions/dev-team/lib/usage-view.ts

@@ -0,0 +1,109 @@
+/**
+ * The /dev-team usage overlay component. It holds the state machine's state (usage-state.ts), turns
+ * keys into transitions, runs this month's load and hands the model to renderUsage (usage-render.ts).
+ */
+import type { Component } from "@earendil-works/pi-tui";
+import type { SpendRun } from "./session-spend.ts";
+import { type MonthSnapshot, monthSnapshot, type UsageBreakdown, usageBreakdown } from "./usage-breakdown.ts";
+import type { LoadOptions, SpendHistory } from "./usage-history.ts";
+import { usageMonthStart } from "./ai-credits.ts";
+import { renderUsage, type UsageStyle } from "./usage-render.ts";
+import { reduce, type Transition, type UsageAction, type UsageEffect, type UsageState, usageKeyFor } from "./usage-state.ts";
+import { errorReason } from "./usage-text.ts";
+
+/** The overlay may take this share of the terminal's height; the command passes the same to pi as `maxHeight`. */
+export const OVERLAY_HEIGHT_PERCENT = 90;
+
+export interface UsageViewDeps {
+	/** This session's runs; read again after `invalidate()`. */
+	sessionRuns(): readonly SpendRun[];
+	now(): Date;
+	/** The terminal's height in rows. */
+	terminalRows(): number;
+	style: UsageStyle;
+	requestRender(): void;
+	/** Closes the overlay. */
+	close(): void;
+	/** Reads this month's spend from the saved sessions; the view cancels it through `signal`. */
+	loadHistory(options: Required<Omit<LoadOptions, "root">>): Promise<SpendHistory>;
+}
+
+/** The overlay component: owns the state, turns keys into transitions, runs the month's load and renders the model. */
+export class UsageView implements Component {
+	private readonly deps: UsageViewDeps;
+	private state: UsageState;
+	private session: UsageBreakdown | undefined;
+	private month: MonthSnapshot | undefined;
+	/** The load in flight. Whatever else holds a different controller (or none) is a stale load whose news is dropped. */
+	private activeLoad: AbortController | undefined;
+
+	constructor(deps: UsageViewDeps, initial: Transition) {
+		this.deps = deps;
+		this.state = initial.state;
+		this.runEffects(initial.effects);
+	}
+
+	render(width: number): string[] {
+		this.session ??= usageBreakdown(this.deps.sessionRuns());
+		const height = Math.max(1, Math.floor((this.deps.terminalRows() * OVERLAY_HEIGHT_PERCENT) / 100));
+		return renderUsage({ state: this.state, session: this.session, month: this.month, now: this.deps.now() }, { width, height, style: this.deps.style });
+	}
+
+	handleInput(data: string): void {
+		const key = usageKeyFor(data);
+		if (key) this.dispatch({ type: "key", key });
+	}
+
+	invalidate(): void {
+		this.session = undefined;
+	}
+
+	/** Called by pi when the overlay goes away; a load still running is of no use any more. */
+	dispose(): void {
+		this.cancelLoad();
+	}
+
+	private dispatch(action: UsageAction): void {
+		const { state, effects } = reduce(this.state, action);
+		this.state = state;
+		this.runEffects(effects);
+		this.deps.requestRender();
+	}
+
+	private runEffects(effects: readonly UsageEffect[]): void {
+		for (const effect of effects) {
+			if (effect === "start-load") this.startLoad();
+			else if (effect === "cancel-load") this.cancelLoad();
+			else this.deps.close();
+		}
+	}
+
+	private startLoad(): void {
+		const controller = new AbortController();
+		this.activeLoad = controller;
+		const isCurrentLoad = () => this.activeLoad === controller;
+		const since = usageMonthStart(this.deps.now());
+		const onProgress = (done: number, total: number) => {
+			if (isCurrentLoad()) this.dispatch({ type: "progress", done, total });
+		};
+		// The snapshot is built inside the async function, so anything it throws is a failed load too.
+		(async () => monthSnapshot(await this.deps.loadHistory({ since, signal: controller.signal, onProgress }), this.deps.now()))().then(
+			(snapshot) => {
+				if (!isCurrentLoad()) return;
+				this.activeLoad = undefined;
+				this.month = snapshot;
+				this.dispatch({ type: "loaded" });
+			},
+			(err: unknown) => {
+				if (!isCurrentLoad()) return;
+				this.activeLoad = undefined;
+				this.dispatch({ type: "failed", reason: errorReason(err) });
+			},
+		);
+	}
+
+	private cancelLoad(): void {
+		this.activeLoad?.abort();
+		this.activeLoad = undefined;
+	}
+}

package/hooks/agent_dispatch_ledger.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+"""agent_dispatch_ledger.py — PreToolUse dispatch-ledger hook (#1461).
+
+Registered in `settings.json`'s existing `PreToolUse` `"Agent|Task"` matcher
+(alongside `subagent_skill_context.py`). Records a `boundary-events.jsonl`
+`"record"` event whenever a genuine review-agent dispatch fires, so
+`hooks/pre_commit_review.py`'s `.review-passed` gate can later corroborate
+that a hash-matching write was backed by real, independent Agent-tool
+dispatches — not just a self-computed hash (issue #1461's residual gap; see
+`hooks/lib/review_gate_hash.py`'s own docstring for the full account).
+
+On each Agent/Task dispatch, reads `tool_input.subagent_type`. If and only if
+it is present in `hooks/lib/review_agent_registry`'s closed set of registered
+`agents/*-review.md` stems, records one `"record"` boundary event carrying
+that agent name as `matched_rule`, stamped with a `subject_hash` binding this
+dispatch to whatever content is under review right now, so a review of one
+changeset can't later corroborate an unrelated one (#1461 security review).
+Anything not in the closed set — a typo, a non-review team agent, or a
+fabricated name — is silently NOT recorded, never written as free text:
+matching `boundary_events.py`'s own no-free-text constraint (rule IDs /
+closed-vocabulary values only, never arbitrary strings). `"record"` is a new,
+fifth-plus decision value: an observation, not a block/warn/bypass/
+intervention/revert policy verdict — see `knowledge/telemetry-schema.md` for
+its full documentation.
+
+**`subject_hash` selection (#1904 Bug 2b, revised from the original
+staged-diff-only stamp):** the staged patch (`review_gate_hash()`) is empty
+by definition during a `--since <base>`-scoped `/code-review` run
+(`skills/pr/SKILL.md`'s only path to `gh pr create` — its step 1 requires a
+CLEAN working tree before that review runs, so nothing is ever staged during
+it). Stamping the constant `EMPTY_DIGEST` in that case would be exactly the
+Bug 1 hazard `review_gate_hash.py`'s own docstring warns against, AND it
+would leave this hook's evidence unable to corroborate
+`hooks/pre_pr_review.py`'s gate at all for that mode (that gate always
+compares against `branch_diff_gate_hash()`, never the staged-diff hash).
+So: when the staged diff is empty, fall back to
+`branch_diff_gate_hash(default_base_ref(cwd), cwd)` — the SAME content
+domain `hooks/pre_pr_review.py` checks and `skills/code-review/SKILL.md`
+step 9 now writes for a `--since <base>`-scoped review — and refuse to stamp
+(`None`) rather than fall back to the empty digest a second time. The
+ordinary auto-scope path (something IS staged) is unchanged: it still stamps
+`review_gate_hash()`, matching step 9's own disclosed "identical only in the
+common single-commit-then-PR shape" limitation for that mode.
+
+Fail-open, matching this codebase's own hook convention (and
+`emit_boundary_event`'s own fail-open write side): any error here — a
+missing/unreadable `agents/` directory, a malformed payload, an exception
+from the shared helper — must never block a real Agent dispatch. This hook
+always exits 0.
+
+KNOWN RESIDUAL GAP (#1461 security re-review): this module is itself a
+directly executable script that reads an attacker-/self-controlled stdin
+payload. Anyone with Bash access to this repo can run
+`echo '{"tool_name":"Task","tool_input":{"subagent_type":"security-review"},
+"cwd":"."}' | python3 hooks/agent_dispatch_ledger.py` (repeated with a second
+registered agent stem) and produce two byte-genuine "record" rows, correctly
+subject-hash-bound, with NO actual Agent/Task dispatch ever occurring. Locking
+down `boundary_events.py`'s CLI (this module's sibling forgery vector) does
+not close this one — the forge just moves one file over. Registered agent
+names are public filenames, so the registry re-validation in
+`review_gate_corroboration.py` does not help either. This is not fixable at
+this module's level: it requires the harness itself to supply something a
+hand-run process cannot fabricate (a signed dispatch receipt, or a
+session/turn-identity check against a live stream the harness — not this
+script — controls). Until that exists, this control raises the bar against
+an agent that takes an *accidental* self-certification shortcut under
+ambiguity (this issue's original, observed failure mode); it is not effective
+against a deliberate, adversarial bypass. See
+`hooks/pre_commit_review.py`'s module docstring for the matching disclosure
+on the read side.
+
+Contract (docs/python-hook-contract.md):
+    Input : PreToolUse JSON on stdin (Agent/Task matcher)
+    Output: always exit 0 — fail-open, this hook never blocks a dispatch.
+
+Stdlib only. See ADR 0014 / ADR 0015.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_HOOK_DIR = Path(__file__).resolve().parent
+_LIB_DIR = _HOOK_DIR / "lib"
+if str(_LIB_DIR) not in sys.path:
+    sys.path.insert(0, str(_LIB_DIR))
+
+from boundary_events import emit_boundary_event as _emit_boundary_event
+from review_agent_registry import is_registered_review_lens, strip_plugin_prefix
+from review_gate_hash import (
+    EMPTY_DIGEST,
+    branch_diff_gate_hash,
+    default_base_ref,
+    review_gate_hash,
+)
+from stdin_json import read_stdin_json
+
+
+def emit_boundary_event(*args, **kwargs) -> None:
+    """Local safety net (#859): even a misbehaving helper must never affect
+    this hook's exit code, stdout, or stderr."""
+    try:
+        _emit_boundary_event(*args, **kwargs)
+    except Exception:  # noqa: BLE001, S110 - fail-open by design
+        pass
+
+
+def main() -> int:
+    payload = read_stdin_json()
+    if payload is None:
+        # Empty or malformed stdin -> silent-pass.
+        return 0
+
+    tool_input = payload.get("tool_input")
+    if not isinstance(tool_input, dict):
+        return 0
+
+    subagent_type = tool_input.get("subagent_type")
+    if not isinstance(subagent_type, str) or not subagent_type:
+        return 0
+
+    # `is_registered_review_lens()` (review_agent_registry.py) owns the
+    # strip-prefix + registry-read + membership check, including the
+    # "unreadable registry collapses to skip" posture — this is the
+    # WRITE/POSITIVE-evidence side (recording that a dispatch happened),
+    # where collapsing an unreadable registry to "don't record" is the safe
+    # direction: narrowing corroboration can only narrow, never widen, what
+    # counts as a passing gate later.
+    if not is_registered_review_lens(subagent_type):
+        # Not a real, registered review agent, or the registry could not be
+        # read at all — never recorded, not even as a rejected/flagged entry
+        # (module docstring).
+        return 0
+
+    # Normalize the plugin-qualified dispatch form ("dev-team:doc-review") to
+    # the bare name the registry's closed set uses, so the plugin's normal,
+    # installed invocation form is recognized identically to a bare-named one.
+    subagent_type = strip_plugin_prefix(subagent_type)
+
+    cwd = payload.get("cwd") or "."
+    session_id = payload.get("session_id")
+    tool_name = payload.get("tool_name") or "Agent"
+
+    # Stamp the CURRENT content hash (#1461 security review, revised #1904
+    # Bug 2b) — binds this dispatch to whatever is under review right now,
+    # so the corroboration reader can require dispatch evidence for the SAME
+    # content as the eventual `.pr-review-passed` write, not merely "some
+    # review happened recently" against unrelated content. A hash-
+    # computation failure (e.g. no git repo) fails open per this hook's own
+    # convention: still record the dispatch, just without a subject_hash —
+    # such an event can never satisfy a gate check, which requires an exact
+    # hash match, so this can only ever under-record, never forge evidence.
+    try:
+        subject_hash = review_gate_hash(cwd)
+        if subject_hash == EMPTY_DIGEST:
+            # Nothing staged — the routine state during a `--since <base>`-
+            # scoped review (skills/pr/SKILL.md requires a clean working
+            # tree before that review runs). Stamping EMPTY_DIGEST here
+            # would be the exact Bug 1 hazard (a constant shared by every
+            # such dispatch, regardless of real content) AND would leave
+            # this evidence unable to corroborate `hooks/pre_pr_review.py`'s
+            # gate, which always compares against `branch_diff_gate_hash()`.
+            # Fall back to that same content domain; refuse to stamp (None)
+            # rather than fall back to the empty digest a second time.
+            base_ref = default_base_ref(cwd)
+            branch_hash = branch_diff_gate_hash(base_ref, cwd) if base_ref is not None else None
+            subject_hash = (
+                branch_hash if branch_hash and branch_hash != EMPTY_DIGEST else None
+            )
+    except Exception:  # noqa: BLE001 - fail-open: a hash failure never blocks a dispatch
+        subject_hash = None
+
+    emit_boundary_event(
+        cwd,
+        "agent_dispatch_ledger",
+        tool_name,
+        "record",
+        subagent_type,
+        session_id,
+        subject_hash=subject_hash,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception:  # noqa: BLE001 - fail-open: a hook bug must never block a dispatch
+        sys.exit(0)

package/hooks/autocompact_setup_nudge.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""autocompact_setup_nudge — Claude Code SessionStart hook (#2177, slice 3).
+
+The plugin no longer forces a handoff at a context ceiling; instead
+`/dev-team:setup` sets the harness's own `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`.
+That makes `/setup` load-bearing, so this hook advises running it when a repo
+shows no sign it has been.
+
+Channel: plain stdout (`sys.stdout.write`), matching the other nudge hooks
+(`repo_review_nudge.py`, `mcp_json_repowise_nudge.py`). Like them it is
+self-silencing from state — once the key is configured it never prints — and
+has no once-per-session marker.
+
+- Key absent (process env, settings.local.json, settings.json, user settings):
+  one advisory line.
+- Key present but invalid (not an integer 1-100): one corrective line.
+- Key valid, opted out, or SessionStart source is "compact": silent.
+
+Opt-out: `DEV_TEAM_AUTOCOMPACT_NUDGE=0` or the marker file
+`.claude/memory/autocompact-nudge-off` (written by `/setup --no-autocompact`).
+
+Project dir: `$CLAUDE_PROJECT_DIR`, else the payload `cwd`, else the process
+cwd. Advisory only: fail-open, always exits 0, never blocks session start.
+Stdlib only.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+_LIB = Path(__file__).resolve().parent / "lib"
+if str(_LIB) not in sys.path:
+    sys.path.insert(0, str(_LIB))
+
+from autocompact_config import KEY, Status, detect  # type: ignore[import-not-found]
+from stdin_json import read_stdin_json, resolve_cwd  # type: ignore[import-not-found]
+
+OPT_OUT_ENV = "DEV_TEAM_AUTOCOMPACT_NUDGE"
+OPT_OUT_MARKER = Path(".claude") / "memory" / "autocompact-nudge-off"
+
+ABSENT_MESSAGE = (
+    "dev-team: context autocompact is not configured for this repo; "
+    "run /dev-team:setup to set it (default 40%). "
+    f"Silence: {OPT_OUT_ENV}=0 or create {OPT_OUT_MARKER.as_posix()}\n"
+)
+
+
+_MAX_SHOWN = 40
+
+
+def invalid_message(raw: object, source: str | None) -> str:
+    shown = repr(raw)
+    if len(shown) > _MAX_SHOWN:
+        shown = shown[: _MAX_SHOWN - 3] + "..."
+    where = f" in {source}" if source else ""
+    return (
+        f"dev-team: {KEY}={shown}{where} is invalid (need integer 1-100); "
+        "re-run /dev-team:setup\n"
+    )
+
+
+def _project_dir(payload: dict) -> Path:
+    override = os.environ.get("CLAUDE_PROJECT_DIR")
+    if override and Path(override).is_dir():
+        return Path(override)
+    return Path(resolve_cwd(payload))
+
+
+def message_for(payload: dict) -> str:
+    """The text to print, or '' when the hook should stay silent."""
+    if payload.get("source") == "compact":
+        return ""
+    if os.environ.get(OPT_OUT_ENV) == "0":
+        return ""
+    project = _project_dir(payload)
+    if (project / OPT_OUT_MARKER).exists():
+        return ""
+    detection = detect(project, os.environ)
+    if detection.status is Status.ABSENT:
+        return ABSENT_MESSAGE
+    if detection.status is Status.INVALID:
+        return invalid_message(detection.raw, detection.source)
+    return ""
+
+
+def main() -> int:
+    try:
+        text = message_for(read_stdin_json() or {})
+        if text:
+            sys.stdout.write(text)
+    except Exception:  # noqa: BLE001 - advisory hook: never block session start
+        return 0
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())