ytdb-slate 0.1.0

package/extension/handoff.ts

@@ -0,0 +1,271 @@
+/**
+ * Auto-pause + handoff: context-budget discipline for the orchestrator.
+ *
+ * Monitoring: after every turn, when orchestrator mode is on and context usage
+ * crosses pauseThresholdPercent (default 40), the store is paused — the thread
+ * tool then rejects NEW dispatches (in-flight ones finish) — and the
+ * orchestrator is steered to produce a handoff brief for the user.
+ *
+ * /slate handoff [focus] → startHandoff(): captures the orchestrator's last
+ * assistant message as the brief, writes <config dir>/slate/pending-handoff.json
+ * (state snapshot + brief + parent session), and opens a fresh session.
+ *
+ * Adoption: session replacement tears down this extension instance, so
+ * in-memory state cannot cross over; and the fresh session's own file has no
+ * slate-state entries for restore() to find (they live in the parent's file).
+ * The pending file bridges the gap: the NEW instance's session_start handler
+ * adopts the snapshot when the fresh session's parentSession header matches
+ * (trusted projects only; stale files are reaped regardless of trust).
+ */
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import {
+	CONFIG_DIR_NAME,
+	type ExtensionAPI,
+	type ExtensionCommandContext,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { orchestratorCostUsd, type SlateConfig, type SlateSnapshot, type SlateStore } from "./state.ts";
+
+const DEFAULT_PAUSE_THRESHOLD_PERCENT = 40;
+/** A pending-handoff file older than this cannot belong to an in-flight handoff. */
+const PENDING_MAX_AGE_MS = 15 * 60 * 1000;
+const BRIEF_MAX_CHARS = 6000;
+
+interface PendingHandoff {
+	parentSession: string | undefined; // undefined = in-memory session; adoption then never matches
+	createdAt: number;
+	brief: string;
+	snapshot: SlateSnapshot;
+}
+
+export interface SlateHandoffHooks {
+	startHandoff(ctx: ExtensionCommandContext, focus?: string): Promise<void>;
+}
+
+function pendingFile(cwd: string): string {
+	return join(cwd, CONFIG_DIR_NAME, "slate", "pending-handoff.json");
+}
+
+/** Last assistant message text on the current branch (the handoff brief). */
+function lastAssistantText(ctx: ExtensionCommandContext): string {
+	let text = "";
+	for (const entry of ctx.sessionManager.getBranch()) {
+		const e = entry as {
+			type: string;
+			message?: { role?: string; content?: string | Array<{ type: string; text?: string }> };
+		};
+		if (e.type !== "message" || e.message?.role !== "assistant") continue;
+		const content = e.message.content;
+		// Entries come from JSON on disk; content may not match the declared
+		// shape. Skip anything that is neither string nor block array.
+		if (typeof content !== "string" && !Array.isArray(content)) continue;
+		const t = (typeof content === "string"
+			? content
+			: content
+					.filter((c) => c.type === "text")
+					.map((c) => c.text ?? "")
+					.join("\n")
+		).trim();
+		if (t) text = t;
+	}
+	return text.length > BRIEF_MAX_CHARS ? `${text.slice(0, BRIEF_MAX_CHARS)}\n[... brief truncated]` : text;
+}
+
+// Trust gate: the project-supplied kickoff template is a project-derived
+// read injected into the fresh session's first prompt, so it is honored
+// only for trusted projects; untrusted → built-in kickoff text.
+function buildKickoff(cwd: string, trusted: boolean, brief: string, focus?: string): string {
+	const template = join(cwd, CONFIG_DIR_NAME, "slate-handoff.md");
+	let base: string | undefined;
+	if (trusted) {
+		// existsSync alone is not enough: the path may be a directory or
+		// unreadable, and a throw escaping here would strand the pending-handoff
+		// file startHandoff just wrote — fall back to the default kickoff text.
+		try {
+			if (existsSync(template)) base = readFileSync(template, "utf8").trim();
+		} catch {
+			/* unreadable template → default kickoff */
+		}
+	}
+	// The "already restored" claim is only valid when the successor session
+	// will actually adopt the pending state — adoption is trust-gated, and the
+	// successor (same process, same cwd) shares this session's trust state, so
+	// `trusted` decides which default text is honest here.
+	if (!base) {
+		base = trusted
+			? [
+					"Slate orchestrator handoff (context hygiene; the previous orchestrator exceeded its context budget).",
+					"Orchestrator mode and all worker threads/episodes from the previous session are already restored:",
+					"use `threads` to list them and `episode` to fetch details. Continue the work.",
+				].join("\n")
+			: [
+					"Slate orchestrator handoff (context hygiene; the previous orchestrator exceeded its context budget).",
+					"NOTE: this project is untrusted, so slate did NOT auto-restore the previous session's threads/episodes.",
+					`Run /slate on if needed, then reconstruct context from the episode files under ${CONFIG_DIR_NAME}/slate/episodes/ and continue the work.`,
+				].join("\n");
+	}
+	const parts = [base];
+	if (brief) parts.push("", "## Handoff brief from the previous orchestrator", "", brief);
+	if (focus) parts.push("", `Immediate focus: ${focus}`);
+	return parts.join("\n");
+}
+
+export function registerSlateHandoff(
+	pi: ExtensionAPI,
+	store: SlateStore,
+	getConfig: () => SlateConfig,
+): SlateHandoffHooks {
+	const checkBudget = (ctx: ExtensionContext) => {
+		if (!store.orchestratorMode || store.paused) return;
+		const percent = ctx.getContextUsage()?.percent;
+		if (percent == null) return;
+		// slate.json is user-edited: accept only finite (0, 100] thresholds.
+		const configured = getConfig().pauseThresholdPercent;
+		const threshold =
+			typeof configured === "number" && Number.isFinite(configured) && configured > 0 && configured <= 100
+				? configured
+				: DEFAULT_PAUSE_THRESHOLD_PERCENT;
+		if (percent < threshold) return;
+
+		store.paused = true;
+		store.save();
+		const pct = Math.round(percent);
+		if (ctx.hasUI) {
+			ctx.ui.notify(
+				`slate: context at ${pct}% (budget ${threshold}%) — paused. Run /slate handoff [focus] to continue in a fresh session.`,
+				"warning",
+			);
+		}
+		pi.sendMessage(
+			{
+				customType: "slate-pause",
+				content: [
+					`[slate] Context is at ${pct}% — over the ${threshold}% budget. Slate auto-paused: the thread tool now REJECTS new dispatches.`,
+					"Finish nothing new. Reply to the user with:",
+					"(1) a concise HANDOFF BRIEF — overall goal, per-thread state with episode ids, immediate next actions;",
+					"(2) instructions: run /slate handoff [optional focus] to continue in a fresh session where all threads and episodes are restored automatically;",
+					`alternatively, start a new pi session manually, run /slate on, and have the new orchestrator read the episode files under ${CONFIG_DIR_NAME}/slate/episodes/.`,
+				].join("\n"),
+				display: true,
+			},
+			{ deliverAs: "steer", triggerTurn: true },
+		);
+	};
+
+	pi.on("turn_end", async (_event, ctx) => checkBudget(ctx));
+	pi.on("agent_end", async (_event, ctx) => checkBudget(ctx));
+
+	// Adopt a pending handoff into a fresh session. Registered AFTER index.ts's
+	// restore handler (so a branch that already carries slate state wins) and
+	// BEFORE mode.ts's (so its tool restriction sees the adopted mode).
+	pi.on("session_start", async (_event, ctx) => {
+		if (store.threads.size > 0 || store.orchestratorMode) return; // state already restored on this branch
+		const file = pendingFile(ctx.cwd);
+		try {
+			if (!existsSync(file)) return;
+			const pending = JSON.parse(readFileSync(file, "utf8")) as PendingHandoff;
+			const age = Date.now() - (pending.createdAt ?? 0);
+			// STALE reap runs regardless of trust: it deletes an abandoned runtime
+			// file without injecting any content into prompts or state, and keeps
+			// the file from lingering forever in a never-trusted project.
+			if (age >= PENDING_MAX_AGE_MS) {
+				rmSync(file, { force: true });
+				return;
+			}
+			// Trust gate (ADOPTION only): the pending file is project-local state a
+			// cloned repo could ship pre-seeded. Never adopt its content in an
+			// untrusted project — but leave a FRESH file untouched: the user may
+			// grant trust shortly after, within the handoff window.
+			if (!ctx.isProjectTrusted()) return;
+			// Never adopt into an unrelated session.
+			const matches = !!pending.parentSession && pending.parentSession === ctx.sessionManager.getHeader()?.parentSession;
+			if (!matches) return;
+			store.adoptSnapshot(pending.snapshot, ctx);
+			store.paused = false;
+			store.save();
+			rmSync(file, { force: true });
+			if (ctx.hasUI) {
+				const t = store.threads.size;
+				const e = store.episodes.size;
+				ctx.ui.notify(
+					`slate: handoff state restored (${t} thread${t === 1 ? "" : "s"}, ${e} episode${e === 1 ? "" : "s"}).`,
+					"info",
+				);
+			}
+		} catch {
+			/* a broken pending file must never break session start */
+		}
+	});
+
+	const startHandoff = async (ctx: ExtensionCommandContext, focus?: string): Promise<void> => {
+		await ctx.waitForIdle();
+
+		const brief = lastAssistantText(ctx);
+		const parentSession = ctx.sessionManager.getSessionFile();
+		const pending: PendingHandoff = {
+			parentSession,
+			createdAt: Date.now(),
+			brief,
+			// The successor starts unpaused and in orchestrator mode regardless of
+			// the current (paused) state.
+			snapshot: {
+				...store.snapshot(),
+				paused: false,
+				orchestratorMode: true,
+				// The successor's own branch sum starts at zero, so bank the parent's
+				// billed orchestrator spend (plus anything already carried) — the
+				// displayed total must survive repeated handoffs.
+				carriedCostUsd: store.carriedCostUsd + orchestratorCostUsd(ctx),
+			},
+		};
+		const file = pendingFile(ctx.cwd);
+		mkdirSync(dirname(file), { recursive: true });
+		writeFileSync(file, `${JSON.stringify(pending, null, 2)}\n`, "utf8");
+
+		const kickoff = buildKickoff(ctx.cwd, ctx.isProjectTrusted(), brief, focus);
+		// catch, NOT finally: on success the NEW session's adoption handler has
+		// already consumed and deleted the pending file (session_start fires
+		// inside newSession) — cleaning up there would be wrong.
+		try {
+			const { cancelled } = await ctx.newSession({
+				parentSession,
+				withSession: async (fresh) => {
+					await fresh.sendUserMessage(kickoff);
+				},
+			});
+			if (cancelled) {
+				// Left behind, the pending file could be adopted by an unintended fork
+				// or session sharing this parent within the 15-min window.
+				rmSync(file, { force: true });
+				store.paused = false;
+				store.save();
+				if (ctx.hasUI) ctx.ui.notify("slate: handoff cancelled — pause cleared, pending state removed.", "warning");
+			}
+		} catch (error) {
+			try {
+				rmSync(file, { force: true });
+			} catch {
+				/* ignore */
+			}
+			// Best-effort: if the replacement partially happened, the old pi/ctx
+			// are stale and these calls themselves throw.
+			try {
+				store.paused = false;
+				store.save();
+				if (ctx.hasUI) {
+					ctx.ui.notify(
+						`slate: handoff failed — ${error instanceof Error ? error.message : String(error)}. Pause cleared; pending state removed.`,
+						"error",
+					);
+				}
+			} catch {
+				/* stale pi/ctx after partial replacement */
+			}
+			throw error;
+		}
+	};
+
+	return { startHandoff };
+}

package/extension/index.ts

@@ -0,0 +1,84 @@
+/**
+ * Slate — thread-weaving agent architecture for pi.
+ *
+ * Implements the Slate architecture — design rationale and principles in
+ * ../docs/design-principles.md (module headers cite decision ids D3–D9/M1–M3 from
+ * the original ExecPlan, which is not in-repo). An orchestrator (the main pi
+ * session) dispatches bounded actions to persistent worker threads via the
+ * `thread` tool; each completed action returns an episode — a compressed,
+ * structured record that the orchestrator composes into further dispatches.
+ *
+ * Modules:
+ *   state.ts    — thread/episode records, session-scoped persistence
+ *   worker.ts   — in-process worker AgentSessions (recursion-guarded)
+ *   episodes.ts — episode compression (Sonnet-default, D5)
+ *   threads.ts  — ThreadManager: queueing, dispatch lifecycle
+ *   tools.ts    — thread / threads / episode tools
+ *   handoff.ts  — context-budget auto-pause + fresh-session handoff
+ *
+ * Optional config at <config dir>/slate.json (config dir = CONFIG_DIR_NAME,
+ * ".pi" by default), honored ONLY when the project is trusted — untrusted
+ * projects run on built-in defaults with no project file injection:
+ *   { "episodeModel": "provider/id", "workerTools": [...], "maxConcurrent": 4,
+ *     "pauseThresholdPercent": 40, "orchestratorModeDefault": true,
+ *     "orchestratorPromptDocs": ["docs/orchestrator-guidelines.md"],
+ *     "workerPromptDocs": ["docs/thread-guidelines.md"],
+ *     "workflow": { "draftPRs": false },
+ *     "doctrineExtraPath": "docs/project-doctrine.md",
+ *     "reviewPerspectivesPath": "docs/review-perspectives.md" }
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CONFIG_DIR_NAME, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerSlateHandoff } from "./handoff.ts";
+import { registerSlateMode } from "./mode.ts";
+import { SlateStore, type SlateConfig } from "./state.ts";
+import { ThreadManager } from "./threads.ts";
+import { registerSlateTools } from "./tools.ts";
+
+function loadConfig(cwd: string): SlateConfig {
+	const file = join(cwd, CONFIG_DIR_NAME, "slate.json");
+	try {
+		if (existsSync(file)) {
+			// JSON.parse accepts any JSON value; only a non-null plain object is a
+			// usable config — a literal `null`, array, or scalar would crash
+			// consumers, so anything else falls through to defaults, silently,
+			// like any other malformed config.
+			const parsed: unknown = JSON.parse(readFileSync(file, "utf8"));
+			if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+				return parsed as SlateConfig;
+			}
+		}
+	} catch {
+		/* invalid config → defaults */
+	}
+	return {};
+}
+
+export default function (pi: ExtensionAPI) {
+	const store = new SlateStore(pi);
+	let manager = new ThreadManager(store, {});
+
+	registerSlateTools(pi, store, () => manager);
+
+	pi.on("session_start", async (_event, ctx) => {
+		manager.disposeAll();
+		// Trust gate: project config steers prompts, models, and tool lists, so
+		// it is honored only for trusted projects; untrusted → built-in defaults.
+		manager = new ThreadManager(store, ctx.isProjectTrusted() ? loadConfig(ctx.cwd) : {});
+		store.restore(ctx);
+	});
+
+	pi.on("session_shutdown", async () => {
+		manager.disposeAll();
+	});
+
+	// session_start ordering (registration order): restore → adopt pending
+	// handoff → re-apply mode tools. registerSlateHandoff must therefore sit
+	// between the restore handler above and registerSlateMode below.
+	// getConfig reads the CURRENT `manager` (reassigned on session_start).
+	const handoff = registerSlateHandoff(pi, store, () => manager.getConfig());
+
+	registerSlateMode(pi, store, handoff, () => manager.getConfig());
+}

package/extension/mode.ts

@@ -0,0 +1,283 @@
+/**
+ * Orchestrator mode (ExecPlan M2, D4).
+ *
+ * `/slate` toggles orchestrator mode:
+ *   - active tools restricted to read-only + slate tools (no bash/edit/write):
+ *     delegation becomes the natural behavior;
+ *   - the thread-weaving doctrine is appended to the system prompt each turn;
+ *   - a widget above the editor shows live thread status;
+ *   - the mode persists in slate state and is re-applied on session restore;
+ *   - with config `orchestratorModeDefault` (slate.json), genuinely fresh
+ *     interactive sessions are seeded with the mode ON (unsaved until the
+ *     first real state mutation).
+ *
+ * `/slate handoff [focus]` / `/slate resume` interact with the auto-pause
+ * machinery in handoff.ts (context budget → paused → fresh-session handoff).
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { SlateHandoffHooks } from "./handoff.ts";
+import {
+	DESIGN_PRINCIPLES_DOC,
+	PR_PUBLISHING_DOC,
+	REVIEW_RULES_DOC,
+	TRACK_WORKFLOW_DOC,
+} from "./paths.ts";
+import { loadPromptDocs } from "./prompt-docs.ts";
+import { orchestratorCostUsd, type SlateConfig, type SlateStore } from "./state.ts";
+
+const ORCHESTRATOR_TOOLS = ["read", "grep", "find", "ls", "thread", "threads", "episode"];
+
+/**
+ * Build the orchestrator doctrine. Rules 8–10 reference the package-shipped
+ * workflow/review/design docs by ABSOLUTE path (paths.ts) so they resolve
+ * wherever the package is installed. Rules 8 and 9 carry config-dependent
+ * tails (workflow.draftPRs, reviewPerspectivesPath), so the doctrine is
+ * assembled per prompt rather than kept as a constant. Project-derived
+ * additions (rule 9's perspectives pointer) apply only when `trusted` and
+ * the file exists (cwd-resolved) — missing files are skipped silently like
+ * every other project doc.
+ */
+function buildDoctrine(cwd: string, config: SlateConfig, trusted: boolean): string {
+	// Rule 8 tail: with draft-PR publishing enabled, the umbrella draft PR is
+	// one of the gates; otherwise durable records live in the workflow log.
+	const rule8Tail =
+		config.workflow?.draftPRs === true
+			? `An umbrella draft PR is part of the pre-implementation gates; PR
+   publishing mechanics are in ${PR_PUBLISHING_DOC}.`
+			: `Durable workflow records anchor in the retained repo-root workflow
+   log per the workflow doc.`;
+	const perspectives = config.reviewPerspectivesPath;
+	const rule9Tail =
+		trusted && typeof perspectives === "string" && perspectives && existsSync(resolve(cwd, perspectives))
+			? `
+   Project-specific review perspectives are defined in ${perspectives} —
+   load them alongside the review rules when composing reviewers.`
+			: "";
+	return `
+
+# Slate orchestrator mode
+
+You are the orchestrator of a thread-weaving system. You strategize; worker
+threads execute. Rules:
+
+1. Do tactical work ONLY by dispatching bounded actions via the \`thread\` tool
+   (one action = one clear, completable task). You cannot edit files or run
+   commands yourself.
+2. Dispatch independent actions in PARALLEL by emitting several \`thread\`
+   calls in one turn. Never serialize what can run concurrently.
+3. Reuse a thread for follow-up actions in the same work stream — it
+   remembers its prior episodes. Create a new thread for a new work stream.
+4. Compose context by reference: pass prior episode ids in \`context\` instead
+   of restating their content.
+5. Your read-only tools (read/grep/find/ls) are for cheap orientation only;
+   anything substantial goes to a thread.
+6. After every episode, update your strategy. Episodes marked STATUS: FAILED
+   require adaptation, not blind retry.
+7. Keep your own messages strategic: goals, task routing, synthesis.
+8. Repository changes follow the slate track-based workflow — read
+   ${TRACK_WORKFLOW_DOC}
+   (skip the read if it is already in your context). Before the FIRST
+   dispatch that modifies files, confirm the pre-implementation gates ran
+   (user design review, adversarial review, user-approved scope).
+   ${rule8Tail}
+9. Every non-trivial change gets reviewed before it is declared done.
+   Before dispatching review threads, read
+   ${REVIEW_RULES_DOC}
+   (skip the read if it is already in your context) and follow it.${rule9Tail}
+10. The design principles behind this architecture are documented in
+   ${DESIGN_PRINCIPLES_DOC}.
+   Read that file only when you must reason about slate itself (explaining
+   it, changing the extension, or an unusual routing/compaction decision) —
+   never for routine dispatching. Skip the read if it is already in your
+   context.`;
+}
+
+/**
+ * Project doctrine extension (config doctrineExtraPath): read at prompt-
+ * assembly time so edits are picked up live, appended AFTER the numbered
+ * rules under a labeled section, headed by the configured (cwd-relative)
+ * path as given in config. Missing/unreadable/empty file or a non-string
+ * path → no block, silently (matches the malformed-config behavior of
+ * prompt-docs.ts). Never injected for untrusted projects. Blocks carry NO
+ * separators — the call site prefixes them, like the prompt-doc blocks.
+ */
+function loadDoctrineExtra(cwd: string, config: SlateConfig, trusted: boolean): string[] {
+	const path = config.doctrineExtraPath;
+	if (!trusted || typeof path !== "string" || !path) return [];
+	try {
+		const content = readFileSync(resolve(cwd, path), "utf8").trim();
+		if (!content) return [];
+		return [`# Project doctrine (injected from ${path})\n\n${content}`];
+	} catch {
+		return [];
+	}
+}
+
+const PAUSED_ADDENDUM = `
+
+# PAUSED — context budget exceeded
+
+Slate is paused for handoff: thread dispatches are REJECTED. Do not start new
+work. Reply with a concise handoff brief (overall goal, per-thread state with
+episode ids, immediate next actions) and direct the user to run
+/slate handoff [optional focus].`;
+
+export function registerSlateMode(
+	pi: ExtensionAPI,
+	store: SlateStore,
+	hooks: SlateHandoffHooks,
+	getConfig: () => SlateConfig,
+): void {
+	let savedTools: string[] | undefined;
+	let uiCtx: ExtensionContext | undefined;
+
+	const updateWidget = () => {
+		if (!uiCtx?.hasUI) return;
+		if (!store.orchestratorMode) {
+			uiCtx.ui.setWidget("slate", undefined);
+			uiCtx.ui.setStatus("slate", undefined);
+			return;
+		}
+		// Orchestrator's own spend: summed over ALL entries (billed reality —
+		// abandoned branches still cost money), plus spend carried across handoffs.
+		const orchestratorCost = orchestratorCostUsd(uiCtx);
+		const total = orchestratorCost + store.workerCostUsd + store.carriedCostUsd;
+		// Keep the line short in the common no-handoff case.
+		const carried = store.carriedCostUsd > 0 ? ` + carried $${store.carriedCostUsd.toFixed(4)}` : "";
+		const costLine = `total $${total.toFixed(4)} (me $${orchestratorCost.toFixed(4)} + workers $${store.workerCostUsd.toFixed(4)}${carried})`;
+		uiCtx.ui.setStatus("slate", `slate: orchestrator ⋅ ${costLine}`);
+		const threads = [...store.threads.values()];
+		const lines = [
+			`slate ⋅ orchestrator mode ⋅ ${threads.length} thread${threads.length === 1 ? "" : "s"}`,
+			`  ${costLine}`,
+			...(store.paused ? ["  ⛔ PAUSED (context budget) — run /slate handoff"] : []),
+			...threads.map(
+				(t) =>
+					`  ${t.status === "running" ? "⏳" : "·"} ${t.id} ${t.name} [${t.status}] ${t.episodeIds.length} episode${t.episodeIds.length === 1 ? "" : "s"}`,
+			),
+		];
+		uiCtx.ui.setWidget("slate", lines);
+	};
+
+	const setMode = (on: boolean, persist: boolean) => {
+		if (on && !store.orchestratorMode) {
+			savedTools = pi.getActiveTools();
+			pi.setActiveTools(ORCHESTRATOR_TOOLS);
+		} else if (!on && store.orchestratorMode) {
+			pi.setActiveTools(savedTools ?? [...pi.getAllTools().map((t) => t.name)]);
+			savedTools = undefined;
+		}
+		if (!on) store.paused = false; // a pause is meaningless outside orchestrator mode
+		store.orchestratorMode = on;
+		if (persist) store.save();
+		updateWidget();
+	};
+
+	// Widget refresh whenever slate state changes (dispatch start/end, new threads).
+	store.onDidChange = updateWidget;
+
+	pi.registerCommand("slate", {
+		description: "Slate orchestrator mode: on | off | handoff [focus] | resume (no arg toggles)",
+		handler: async (args, ctx) => {
+			uiCtx = ctx;
+			const trimmed = args?.trim() ?? "";
+			const [verb, ...rest] = trimmed.split(/\s+/);
+			const arg = verb?.toLowerCase();
+			if (arg === "handoff") {
+				if (!store.orchestratorMode) {
+					if (ctx.hasUI) ctx.ui.notify("slate: orchestrator mode is not active — nothing to hand off.", "warning");
+					return;
+				}
+				await hooks.startHandoff(ctx, rest.join(" ") || undefined);
+				return;
+			}
+			if (arg === "resume") {
+				store.paused = false;
+				store.save();
+				if (ctx.hasUI) ctx.ui.notify("slate: pause cleared — dispatches allowed again.", "info");
+				return;
+			}
+			const target = arg === "on" ? true : arg === "off" ? false : !store.orchestratorMode;
+			setMode(target, true);
+			if (ctx.hasUI) {
+				ctx.ui.notify(
+					target
+						? "Slate orchestrator mode ON — tactical tools removed; delegate via the thread tool."
+						: "Slate orchestrator mode OFF — full toolset restored.",
+					"info",
+				);
+			}
+		},
+	});
+
+	pi.on("before_agent_start", async (event, ctx) => {
+		if (!store.orchestratorMode) return;
+		const config = getConfig();
+		// Trust gate: project-derived prompt content (role docs, doctrine extra,
+		// review-perspectives pointer) is injected only for trusted projects.
+		// Config itself is already trust-gated at load (index.ts); checking again
+		// here keeps the file reads safe regardless of where config came from.
+		const trusted = ctx.isProjectTrusted();
+		// Doc CONTENTS are re-read from disk on every agent start, so edits are
+		// picked up live; the doc PATH LIST comes from config, which reloads
+		// only on session_start (index.ts).
+		const docs = trusted ? loadPromptDocs(ctx.cwd, config.orchestratorPromptDocs ?? []) : [];
+		// Blocks carry no separators — prefix each here. When paused, the
+		// addendum goes LAST so the pause directive is the final word in the
+		// prompt, undiluted by the role guidelines.
+		const parts = [
+			buildDoctrine(ctx.cwd, config, trusted),
+			...loadDoctrineExtra(ctx.cwd, config, trusted).map((d) => `\n\n${d}`),
+			...docs.map((d) => `\n\n${d}`),
+		];
+		if (store.paused) parts.push(PAUSED_ADDENDUM);
+		return { systemPrompt: event.systemPrompt + parts.join("") };
+	});
+
+	// Refresh the orchestrator's own cost after each of its settled runs.
+	pi.on("agent_settled", async (_event, ctx) => {
+		uiCtx = ctx;
+		updateWidget();
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		uiCtx = ctx;
+		// store.restore() (index.ts) and pending-handoff adoption (handoff.ts)
+		// ran before this handler in registration order; re-apply the persisted
+		// mode to the fresh runtime.
+		//
+		// Config-driven default: seed orchestrator mode ON for a genuinely FRESH
+		// interactive session. Running AFTER restore and handoff adoption means
+		// the seed can neither clobber persisted state nor trip the adoption
+		// guard. "Fresh" = no message entries and no recorded slate state on the
+		// branch: metadata-only entries (e.g., session naming) don't suppress the
+		// seed, while resumed/forked real sessions and explicit /slate off
+		// decisions stay untouched. Deliberately NOT saved — persisting would
+		// lock the default into old sessions even after the config flag is later
+		// turned off; the first real mutation persists it. The mode === "tui"
+		// gate limits the seed to interactive terminal sessions — hasUI would not
+		// do: it is also true in RPC mode, and scripted/automated runs
+		// (print/JSON/RPC) must not silently lose tactical tools.
+		if (!store.orchestratorMode && ctx.mode === "tui" && getConfig().orchestratorModeDefault === true) {
+			const fresh = !ctx.sessionManager.getBranch().some((entry) => {
+				// Loose cast like state.ts restore(): tolerate malformed/legacy entries.
+				const e = entry as { type: string; customType?: string };
+				return e.type === "message" || (e.type === "custom" && e.customType === "slate-state");
+			});
+			if (fresh) store.orchestratorMode = true;
+		}
+		if (store.orchestratorMode) {
+			const active = pi.getActiveTools();
+			const alreadyRestricted =
+				active.length === ORCHESTRATOR_TOOLS.length && ORCHESTRATOR_TOOLS.every((t) => active.includes(t));
+			// Never capture the restricted set as the thing to restore later —
+			// that would make /slate off a no-op forever.
+			if (!alreadyRestricted) savedTools = active;
+			pi.setActiveTools(ORCHESTRATOR_TOOLS);
+		}
+		updateWidget();
+	});
+}

package/extension/paths.ts

@@ -0,0 +1,19 @@
+/**
+ * Package-relative doc paths.
+ *
+ * The package ships its workflow/review/design docs under docs/ next to
+ * extension/. The orchestrator doctrine (mode.ts) references them by
+ * ABSOLUTE path — resolved from this module's own location via
+ * import.meta.url — so they are readable regardless of the project cwd or
+ * where the package is installed (project-local, user-global, node_modules).
+ */
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const DOCS_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "docs");
+
+export const TRACK_WORKFLOW_DOC = join(DOCS_DIR, "track-workflow.md");
+export const PR_PUBLISHING_DOC = join(DOCS_DIR, "pr-publishing.md");
+export const REVIEW_RULES_DOC = join(DOCS_DIR, "review-rules.md");
+export const DESIGN_PRINCIPLES_DOC = join(DOCS_DIR, "design-principles.md");