@tekmidian/pai 0.42.6 → 0.44.0

package/dist/{wakeup-TnGjJY3I.mjs → wakeup-BfElduEU.mjs}

@@ -1,3 +1,4 @@
+import { a as paiHomePath, r as migratePaiFile } from "./pai-home-ChAOupZc.mjs";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join } from "node:path";
@@ -29,19 +30,31 @@ const EXTRACT_SECTIONS = [
 /** Identity file location. */
 const IDENTITY_FILE = join(homedir(), ".pai", "identity.txt");
 /**
-* Load L0 identity from ~/.pai/identity.txt.
-* Returns the file content, or an empty string if the file does not exist.
-* Never throws.
+* Load L0 identity. Prefers the PAI_HOME location (identity.txt migrated by
+* `pai config migrate`), falling back to the legacy ~/.pai/identity.txt so a
+* not-yet-migrated file keeps working. Returns "" if neither exists. Never
+* throws.
 */
-function loadL0Identity() {
-	if (!existsSync(IDENTITY_FILE)) return "";
+function loadL0Identity(opts = {}) {
+	const newPath = opts.newPath ?? paiHomePath("identity.txt");
+	const legacyPath = opts.legacyPath ?? IDENTITY_FILE;
+	const path = existsSync(newPath) ? newPath : legacyPath;
+	if (!existsSync(path)) return "";
 	try {
-		return readFileSync(IDENTITY_FILE, "utf-8").trim();
+		return readFileSync(path, "utf-8").trim();
 	} catch {
 		return "";
 	}
 }
 /**
+* Move ~/.pai/identity.txt into PAI_HOME, following the same copy /
+* verify-byte-identical / rename-aside semantics as every other per-user
+* file (see migratePaiFile). `from`/`to` are overridable for tests.
+*/
+function migrateIdentityFile(opts = {}) {
+	return migratePaiFile(opts.to ?? paiHomePath("identity.txt"), [opts.from ?? IDENTITY_FILE], { dryRun: opts.dryRun });
+}
+/**
 * Find the Notes directory for a project given its root_path from the registry.
 * Checks local Notes/ first, then central ~/.claude/projects/... path.
 */
@@ -214,5 +227,5 @@ function buildWakeupContext(rootPath, tokenBudget = L1_TOKEN_BUDGET) {
 }
 
 //#endregion
-export { buildWakeupContext as t };
-//# sourceMappingURL=wakeup-TnGjJY3I.mjs.map
+export { migrateIdentityFile as n, buildWakeupContext as t };
+//# sourceMappingURL=wakeup-BfElduEU.mjs.map

package/dist/wakeup-BfElduEU.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"wakeup-BfElduEU.mjs","names":[],"sources":["../src/memory/wakeup.ts"],"sourcesContent":["/**\n * Wake-up context system — progressive context loading inspired by mempalace.\n *\n * Layers:\n *   L0 Identity     (~100 tokens)   — user identity from ~/.pai/identity.txt. Always loaded.\n *   L1 Essential Story (~500-800t)  — top session notes for the project, key lines extracted.\n *   L2 On-Demand                    — triggered by topic queries (handled by memory_search).\n *   L3 Deep Search                  — unlimited federated memory search (memory_search tool).\n */\n\nimport { existsSync, readdirSync, readFileSync, statSync } from \"node:fs\";\nimport { join, basename } from \"node:path\";\nimport { homedir } from \"node:os\";\nimport { paiHomePath, migratePaiFile, type MigrateFileResult } from \"../config/pai-home.js\";\n\n// ---------------------------------------------------------------------------\n// Constants\n// ---------------------------------------------------------------------------\n\n/** Maximum tokens for the L1 essential story block. Approx 4 chars/token.\n * Measured 2026-09-20: 800 tokens was mostly stale bullets. Reduced to 300.\n */\nconst L1_TOKEN_BUDGET = 300;\nconst L1_CHAR_BUDGET = L1_TOKEN_BUDGET * 4; // ~1600 chars\n\n/** Maximum session notes to scan when building L1. Reduced from 10 to 3 (2026-09-20). */\nconst L1_MAX_NOTES = 3;\n\n/** Sections to extract from session notes (in priority order). */\nconst EXTRACT_SECTIONS = [\n  \"Work Done\",\n  \"Key Decisions\",\n  \"Next Steps\",\n  \"Checkpoint\",\n];\n\n/** Identity file location. */\nconst IDENTITY_FILE = join(homedir(), \".pai\", \"identity.txt\");\n\n// ---------------------------------------------------------------------------\n// L0: Identity\n// ---------------------------------------------------------------------------\n\n/**\n * Load L0 identity. Prefers the PAI_HOME location (identity.txt migrated by\n * `pai config migrate`), falling back to the legacy ~/.pai/identity.txt so a\n * not-yet-migrated file keeps working. Returns \"\" if neither exists. Never\n * throws.\n */\nexport function loadL0Identity(\n  opts: { newPath?: string; legacyPath?: string } = {}\n): string {\n  const newPath = opts.newPath ?? paiHomePath(\"identity.txt\");\n  const legacyPath = opts.legacyPath ?? IDENTITY_FILE;\n  const path = existsSync(newPath) ? newPath : legacyPath;\n  if (!existsSync(path)) return \"\";\n  try {\n    return readFileSync(path, \"utf-8\").trim();\n  } catch {\n    return \"\";\n  }\n}\n\n/**\n * Move ~/.pai/identity.txt into PAI_HOME, following the same copy /\n * verify-byte-identical / rename-aside semantics as every other per-user\n * file (see migratePaiFile). `from`/`to` are overridable for tests.\n */\nexport function migrateIdentityFile(\n  opts: { dryRun?: boolean; from?: string; to?: string } = {}\n): MigrateFileResult {\n  const toPath = opts.to ?? paiHomePath(\"identity.txt\");\n  const fromPath = opts.from ?? IDENTITY_FILE;\n  return migratePaiFile(toPath, [fromPath], { dryRun: opts.dryRun });\n}\n\n// ---------------------------------------------------------------------------\n// L1: Essential Story\n// ---------------------------------------------------------------------------\n\n/**\n * Find the Notes directory for a project given its root_path from the registry.\n * Checks local Notes/ first, then central ~/.claude/projects/... path.\n */\nfunction findNotesDirForProject(rootPath: string): string | null {\n  // Check local Notes directories first\n  const localCandidates = [\n    join(rootPath, \"Notes\"),\n    join(rootPath, \"notes\"),\n    join(rootPath, \".claude\", \"Notes\"),\n  ];\n  for (const p of localCandidates) {\n    if (existsSync(p)) return p;\n  }\n\n  // Fall back to central ~/.claude/projects/{encoded}/Notes\n  const encoded = rootPath\n    .replace(/\\//g, \"-\")\n    .replace(/\\./g, \"-\")\n    .replace(/ /g, \"-\");\n  const centralNotes = join(\n    homedir(),\n    \".claude\",\n    \"projects\",\n    encoded,\n    \"Notes\"\n  );\n  if (existsSync(centralNotes)) return centralNotes;\n\n  return null;\n}\n\n/**\n * Recursively find all .md session note files in a Notes directory.\n * Handles both flat layout (Notes/*.md) and month-subdirectory layout\n * (Notes/YYYY/MM/*.md). Returns files sorted newest-first by filename\n * (note numbers are monotonically increasing, so lexicographic = newest-last,\n * so we reverse).\n */\nfunction findSessionNotes(notesDir: string): string[] {\n  const result: string[] = [];\n\n  const scanDir = (dir: string) => {\n    if (!existsSync(dir)) return;\n    let entries: string[];\n    try {\n      entries = readdirSync(dir, { withFileTypes: true } as Parameters<typeof readdirSync>[1] as any)\n        .map((e: any) => ({ name: e.name, isDir: e.isDirectory() }));\n    } catch {\n      return;\n    }\n\n    for (const entry of entries as Array<{ name: string; isDir: boolean }>) {\n      const fullPath = join(dir, entry.name);\n      if (entry.isDir) {\n        // Recurse into YYYY/MM subdirectories\n        scanDir(fullPath);\n      } else if (entry.name.match(/^\\d{3,4}[\\s_-].*\\.md$/)) {\n        result.push(fullPath);\n      }\n    }\n  };\n\n  scanDir(notesDir);\n\n  // Sort newest-first by the DATE in the filename, not the note number.\n  //\n  // The note number is only monotonic within one uninterrupted numbering run.\n  // It restarts — per month directory, and after a registry merge renumbers a\n  // project — so \"highest number\" and \"most recent\" diverge. Observed live:\n  // `0184 - 2026-02-22` outranked `0008 - 2026-08-01`, and the wake-up context\n  // handed a resumed session five-month-old material as its recent history.\n  //\n  // `NNNN - YYYY-MM-DD - Title.md` is the enforced layout, so the date is the\n  // reliable key. Number breaks ties within a day; mtime is the last resort\n  // for notes that predate the naming convention.\n  const dateOf = (p: string): string =>\n    basename(p).match(/(\\d{4}-\\d{2}-\\d{2})/)?.[1] ?? \"\";\n  const numberOf = (p: string): number =>\n    parseInt(basename(p).match(/^(\\d+)/)?.[1] ?? \"0\", 10);\n  const mtimeOf = (p: string): number => {\n    try {\n      return statSync(p).mtimeMs;\n    } catch {\n      return 0;\n    }\n  };\n\n  result.sort((a, b) => {\n    const dateA = dateOf(a);\n    const dateB = dateOf(b);\n    // Undated notes sort last rather than winning on an empty string.\n    if (dateA !== dateB) {\n      if (!dateA) return 1;\n      if (!dateB) return -1;\n      return dateB.localeCompare(dateA);\n    }\n    const byNumber = numberOf(b) - numberOf(a);\n    if (byNumber !== 0) return byNumber;\n    return mtimeOf(b) - mtimeOf(a);\n  });\n\n  return result;\n}\n\n/**\n * Extract the most important lines from a session note.\n * Prioritises: Work Done items, Key Decisions, Next Steps, Checkpoint headings.\n * Returns a condensed string under maxChars.\n */\nfunction normalizeLine(line: string): string {\n  return line\n    .replace(/^(- \\[[ x]\\] |- |\\* |\\d+\\.\\s)/, \"\")\n    .trim()\n    .replace(/\\s+/g, \" \");\n}\n\nfunction extractKeyLines(content: string, maxChars: number, seen: Set<string> = new Set()): string {\n  const lines = content.split(\"\\n\");\n  const selected: string[] = [];\n  let inTargetSection = false;\n  let currentSection = \"\";\n  let charCount = 0;\n\n  // First pass: collect lines from priority sections\n  for (const line of lines) {\n    // Detect section headers\n    const h2Match = line.match(/^## (.+)$/);\n    const h3Match = line.match(/^### (.+)$/);\n    if (h2Match) {\n      currentSection = h2Match[1];\n      inTargetSection = EXTRACT_SECTIONS.some((s) =>\n        currentSection.toLowerCase().includes(s.toLowerCase())\n      );\n      continue;\n    }\n    if (h3Match) {\n      // Checkpoints / sub-sections — include heading as label\n      if (inTargetSection) {\n        const label = `[${h3Match[1]}]`;\n        if (charCount + label.length < maxChars) {\n          selected.push(label);\n          charCount += label.length + 1;\n        }\n      }\n      continue;\n    }\n\n    if (!inTargetSection) continue;\n\n    // Skip blank lines and HTML comments\n    const trimmed = line.trim();\n    if (!trimmed || trimmed.startsWith(\"<!--\") || trimmed === \"---\") continue;\n\n    // Include checkbox items, bold text, and plain text lines\n    if (\n      trimmed.startsWith(\"- \") ||\n      trimmed.startsWith(\"* \") ||\n      trimmed.match(/^\\d+\\./) ||\n      trimmed.startsWith(\"**\")\n    ) {\n      const normalized = normalizeLine(trimmed);\n      if (seen.has(normalized)) continue;\n      if (charCount + trimmed.length + 1 > maxChars) break;\n      seen.add(normalized);\n      selected.push(trimmed);\n      charCount += trimmed.length + 1;\n    }\n  }\n\n  return selected.join(\"\\n\");\n}\n\n/**\n * Build the L1 essential story block.\n *\n * Reads the most recent session notes for the project and extracts the key\n * lines (Work Done, Key Decisions, Next Steps) within the token budget.\n *\n * @param rootPath   The project root path (from the registry).\n * @param tokenBudget  Max tokens to consume. Default 800 (~3200 chars).\n * @returns Formatted L1 block, or empty string if no notes found.\n */\nexport function buildL1EssentialStory(\n  rootPath: string,\n  tokenBudget = L1_TOKEN_BUDGET\n): string {\n  const charBudget = tokenBudget * 4;\n  const notesDir = findNotesDirForProject(rootPath);\n  if (!notesDir) return \"\";\n\n  const noteFiles = findSessionNotes(notesDir).slice(0, L1_MAX_NOTES);\n  if (noteFiles.length === 0) return \"\";\n\n  const sections: string[] = [];\n  const seen = new Set<string>();\n  let remaining = charBudget;\n\n  for (const noteFile of noteFiles) {\n    if (remaining <= 50) break;\n\n    let content: string;\n    try {\n      content = readFileSync(noteFile, \"utf-8\");\n    } catch {\n      continue;\n    }\n\n    // Extract the note date and title from the filename\n    const name = basename(noteFile);\n    const titleMatch = name.match(/^\\d+ - (\\d{4}-\\d{2}-\\d{2}) - (.+)\\.md$/);\n    const dateLabel = titleMatch ? titleMatch[1] : \"\";\n    const titleLabel = titleMatch\n      ? titleMatch[2]\n      : name.replace(/^\\d+ - /, \"\").replace(/\\.md$/, \"\");\n\n    // Skip if nothing useful extracted from this note\n    const perNoteChars = Math.min(remaining, Math.floor(charBudget / noteFiles.length) + 200);\n    const extracted = extractKeyLines(content, perNoteChars, seen);\n    if (!extracted) continue;\n\n    const noteBlock = `[${dateLabel} - ${titleLabel}]\\n${extracted}`;\n    sections.push(noteBlock);\n    remaining -= noteBlock.length + 1;\n  }\n\n  if (sections.length === 0) return \"\";\n\n  return sections.join(\"\\n\\n\");\n}\n\n// ---------------------------------------------------------------------------\n// Combined: buildWakeupContext\n// ---------------------------------------------------------------------------\n\n/**\n * Build the combined wake-up context block (L0 + L1).\n *\n * Returns a formatted string suitable for injection as a system-reminder,\n * or an empty string if both layers are empty.\n *\n * @param rootPath   Project root path for L1 note lookup. Optional.\n * @param tokenBudget  L1 token budget. Default 800.\n */\nexport function buildWakeupContext(\n  rootPath?: string,\n  tokenBudget = L1_TOKEN_BUDGET\n): string {\n  const identity = loadL0Identity();\n  const essentialStory = rootPath\n    ? buildL1EssentialStory(rootPath, tokenBudget)\n    : \"\";\n\n  if (!identity && !essentialStory) return \"\";\n\n  const parts: string[] = [];\n\n  if (identity) {\n    parts.push(`## L0 Identity\\n\\n${identity}`);\n  }\n\n  if (essentialStory) {\n    parts.push(`## L1 Essential Story\\n\\n${essentialStory}`);\n  }\n\n  return parts.join(\"\\n\\n\");\n}\n"],"mappings":"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"}

package/docs/commands/README.md

@@ -45,14 +45,18 @@ Generated man pages for every `pai` command area. Read any page in the terminal
 | Command | Description |
 |---------|-------------|
 | `pai audit` | Diagnostic audits: token-waste report and friends |
-| `pai audit tokens` | Token-waste audit: memory files, hooks, session usage, spawn overhead, daemon, env, schedule |
+| `pai audit tokens` | Token-waste audit: memory files, hooks, session usage, spawn overhead, daemon, env, schedule, skill catalogue, subagents, MCP |
 | `pai audit tokens daemon` | LLM spawns, KG-extraction parse failures, work-queue counts from the daemon log |
 | `pai audit tokens env` | ANTHROPIC_BASE_URL / model-override env on every live claude process |
 | `pai audit tokens files [paths...]` | Token count per memory file (CLAUDE.md chain, CORE skill, whisper rules, auto-memory) |
 | `pai audit tokens hooks` | Token cost of every SessionStart / UserPromptSubmit hook |
+| `pai audit tokens ladder` | LIVE: first-turn context at increasing headless-worker configuration (spawns real claude -p calls) |
+| `pai audit tokens mcp` | MCP servers: configured vs. pinned vs. loaded-live vs. used in the last 30 days |
 | `pai audit tokens schedule` | Launchd agents / crontab entries that outpace the measured prompt-cache TTL |
 | `pai audit tokens session [path]` | Cache/input/output token split for a session transcript (default: newest) |
+| `pai audit tokens skills` | Token cost of the SKILL.md / command / plugin catalogue, top entries, duplicate names |
 | `pai audit tokens spawn` | Spawn-overhead comparison: Agent-tool subagents vs. pai workers |
+| `pai audit tokens subagents` | Token cost of Claude Code subagent definitions (~/.claude/agents, <cwd>/.claude/agents) and their model pinning |
 | `pai backup` | Backup registry, config, and Postgres database to PAI_HOME/backups/ |
 | `pai clear-names` | Recovery: wipe corrupted iTerm2 session name state. |
 | `pai config` | PAI_HOME namespace dir: path, migrate |

package/docs/commands/audit.md

@@ -14,17 +14,18 @@ pai audit <subcommand> [options]
 
 | Command | Description |
 |---------|-------------|
-| [`pai audit tokens`](#pai-audit-tokens) | Token-waste audit: memory files, hooks, session usage, spawn overhead, daemon, env, schedule |
+| [`pai audit tokens`](#pai-audit-tokens) | Token-waste audit: memory files, hooks, session usage, spawn overhead, daemon, env, schedule, skill catalogue, subagents, MCP |
 
 ### pai audit tokens
 
-Token-waste audit: memory files, hooks, session usage, spawn overhead, daemon, env, schedule
+Token-waste audit: memory files, hooks, session usage, spawn overhead, daemon, env, schedule, skill catalogue, subagents, MCP
 
 **Options**
 
 | Option | Description | Default |
 |--------|-------------|---------|
 | `--json` | Print JSON instead of a table |  |
+| `--record <dir>` | Write a dated, numbered markdown+JSON snapshot of the combined report to <dir> |  |
 
 
 ### pai audit tokens files [paths...]
@@ -53,6 +54,12 @@ Cache/input/output token split for a session transcript (default: newest)
 |----------|------|-------------|
 | `[path]` | optional | Session JSONL path (default: newest under ~/.claude/projects) |
 
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--ctx-threshold <n>` | Per-turn context size above which a turn counts as 'above threshold' (default 200000) |  |
+
 
 ### pai audit tokens spawn
 
@@ -63,6 +70,7 @@ Spawn-overhead comparison: Agent-tool subagents vs. pai workers
 | Option | Description | Default |
 |--------|-------------|---------|
 | `-n, --n <count>` | How many of the newest logs per group to read (default 10) |  |
+| `--detail` | Print one row per log (first-turn ctx, prompt tokens, overhead, model, path) |  |
 
 
 ### pai audit tokens daemon
@@ -80,6 +88,46 @@ ANTHROPIC_BASE_URL / model-override env on every live claude process
 Launchd agents / crontab entries that outpace the measured prompt-cache TTL
 
 
+### pai audit tokens skills
+
+Token cost of the SKILL.md / command / plugin catalogue, top entries, duplicate names
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--top <n>` | How many top-by-tokens entries to show (default 15) |  |
+
+
+### pai audit tokens subagents
+
+Token cost of Claude Code subagent definitions (~/.claude/agents, <cwd>/.claude/agents) and their model pinning
+
+
+### pai audit tokens mcp
+
+MCP servers: configured vs. pinned vs. loaded-live vs. used in the last 30 days
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--connect` | Actually connect to every stdio MCP server to count exposed tools (side-effecting; never on by default) |  |
+
+
+### pai audit tokens ladder
+
+LIVE: first-turn context at increasing headless-worker configuration (spawns real claude -p calls)
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--live` | Actually spawn claude -p (billed API traffic); refuses without this flag |  |
+| `--model <model>` | Model to probe with (default haiku) |  |
+| `--mcp-config <path>` | MCP config for the L2 rung (default: newest *.mcp.json in the workers log dir) |  |
+
+
 ## See also
 
 [`pai backup`](backup.md) · [`pai clear-names`](clear-names.md) · [`pai config`](config.md) · [`pai daemon`](daemon.md) · [`pai db`](db.md) · [`pai end`](end.md) · [`pai help`](help.md) · [`pai identity`](identity.md) · [`pai kg`](kg.md) · [`pai launch`](launch.md) · [`pai mcp`](mcp.md) · [`pai memory`](memory.md) · [`pai notify`](notify.md) · [`pai observation`](observation.md) · [`pai obsidian`](obsidian.md) · [`pai pause`](pause.md) · [`pai project`](project.md) · [`pai projects`](projects.md) · [`pai registry`](registry.md) · [`pai restore`](restore.md) · [`pai session`](session.md) · [`pai sessions`](sessions.md) · [`pai setup`](setup.md) · [`pai shell-init`](shell-init.md) · [`pai skill`](skill.md) · [`pai task`](task.md) · [`pai topic`](topic.md) · [`pai update`](update.md) · [`pai worker`](worker.md) · [`pai zettel`](zettel.md)

package/docs/commands/worker.md

@@ -86,6 +86,8 @@ Grant MCP tools by naming mcp__server__tool in --allowedTools (the server loads
 | `--worktree` | Run in a git worktree on branch worker/<id> (default for implement/complex/plan in a git repo) |  |
 | `--no-worktree` | Run in place, no worktree |  |
 | `--print-cmd` | Print the assembled claude argv as JSON and exit, without spawning (audit tool) |  |
+| `--report <format>` | Final-report contract/parser: json or ag2 (default: ag2, or PAI_WORKER_REPORT) |  |
+| `--no-report-retry` | Skip the one bounded re-ask when the final AG2 message fails validation |  |
 
 
 ### pai worker ps

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekmidian/pai",
-  "version": "0.42.6",
+  "version": "0.44.0",
   "description": "PAI Knowledge OS — Personal AI Infrastructure with federated memory and project management",
   "type": "module",
   "main": "dist/index.mjs",

package/scripts/build-hooks.mjs

@@ -238,6 +238,8 @@ if (doSync && isInsideWorkerWorktree(process.cwd())) {
     ["src/hooks/pre-compact.sh", "pai-pre-compact.sh"],
     ["src/hooks/session-stop.sh", "pai-session-stop.sh"],
     ["src/hooks/session-autosave.sh", "pai-session-autosave.sh"],
+    ["src/hooks/ztk-auto.sh", "ztk-auto.sh"],
+    ["src/hooks/ztk-passthrough.mjs", "ztk-passthrough.mjs"],
   ];
   for (const [src, destName] of shellHooks) {
     if (existsSync(src)) {

package/src/hooks/ts/lib/context-fill.test.ts

@@ -632,6 +632,46 @@ describe("contextFillThresholds — trigger source", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// contextFillThresholds — the 2026-09-20 regime change (override 80 -> 20 on
+// a 1M window). Same min(measured, configured) formula, no code change
+// needed, but the specific numbers of that day are worth pinning down: a
+// project's measured history (784k, from the prior 78-79% regime) is now
+// HIGHER than the newly configured 20%-of-1M trigger (200k), so the clamp
+// must take the configured value, not the stale measured one.
+// ---------------------------------------------------------------------------
+
+describe("contextFillThresholds — 2026-09-20 regime change (override 80 -> 20)", () => {
+  it("measured 784k + configured 200k (override=20, 1M window) -> clamps to 200k", () => {
+    const t = contextFillThresholds(readingAt(1_000_000), { CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: "20" }, { measuredTrigger: 784_000 });
+    expect(t.configuredTriggerTokens).toBe(200_000);
+    expect(t.triggerSource).toBe("measured-clamped");
+    expect(t.effectiveTriggerTokens).toBe(200_000);
+    expect(t.warmupTokens).toBe(100_000); // 200,000 - 100,000
+  });
+
+  it("measured 784k + configured 800k (override=80, 1M window) -> measured wins at 784k", () => {
+    const t = contextFillThresholds(readingAt(1_000_000), { CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: "80" }, { measuredTrigger: 784_000 });
+    expect(t.configuredTriggerTokens).toBe(800_000);
+    expect(t.triggerSource).toBe("measured");
+    expect(t.effectiveTriggerTokens).toBe(784_000);
+  });
+
+  it("measured null + configured 200k (override=20, no compaction history yet) -> 200k", () => {
+    const t = contextFillThresholds(readingAt(1_000_000), { CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: "20" }, { measuredTrigger: null });
+    expect(t.triggerSource).toBe("configured");
+    expect(t.effectiveTriggerTokens).toBe(200_000);
+  });
+
+  it("measured 784k + override unset (defaults to 80, configured 800k) -> measured wins at 784k", () => {
+    const t = contextFillThresholds(readingAt(1_000_000), {}, { measuredTrigger: 784_000 });
+    expect(t.autocompactPct).toBe(80);
+    expect(t.configuredTriggerTokens).toBe(800_000);
+    expect(t.triggerSource).toBe("measured");
+    expect(t.effectiveTriggerTokens).toBe(784_000);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Foreign-model transcripts — a headless worker on another provider (a
 // different context window) shares the project folder; its compactions must

package/src/hooks/ts/post-tool-use/whisper-reinject.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, existsSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+// whisper-reinject.ts calls main() unconditionally at module scope, including
+// a read of fd 0 — same reason as session-start-worker-guard.test.ts and
+// user-prompt/whisper-rules.test.ts, run it as a real subprocess with its own
+// piped stdin and an isolated TMPDIR so its counter file never collides with
+// a real session's.
+describe("post-tool-use/whisper-reinject entrypoint", () => {
+  const ENTRYPOINT = "src/hooks/ts/post-tool-use/whisper-reinject.ts";
+  let isolatedTmp: string;
+
+  beforeEach(() => {
+    isolatedTmp = mkdtempSync(join(tmpdir(), "whisper-reinject-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(isolatedTmp, { recursive: true, force: true });
+  });
+
+  function runHook(sessionId: string, env: NodeJS.ProcessEnv = {}): string {
+    return execFileSync("bun", [ENTRYPOINT], {
+      input: JSON.stringify({ session_id: sessionId, hook_event_name: "PostToolUse" }),
+      encoding: "utf8",
+      timeout: 15_000,
+      // This test suite itself may run inside a worker (PAI_WORKER=1 in
+      // process.env) — explicitly clear it so "without the guard" cases are
+      // not silently exercising the guarded path instead.
+      env: { ...process.env, PAI_WORKER: "", TMPDIR: isolatedTmp, ...env },
+    });
+  }
+
+  it("prints nothing and does not touch the counter file when PAI_WORKER=1", () => {
+    const stdout = runHook("t", { PAI_WORKER: "1" });
+    expect(stdout).toBe("");
+
+    const counterDir = join(isolatedTmp, "pai-whisper-reinject");
+    expect(existsSync(counterDir)).toBe(false);
+  });
+
+  it("stays quiet below the threshold and emits the reminder once enough calls have passed", () => {
+    let stdout = "";
+    for (let i = 0; i < 8; i++) {
+      stdout = runHook("t");
+    }
+    expect(stdout).toContain("<system-reminder>");
+    expect(stdout).toContain("tool calls into this turn");
+
+    const counterDir = join(isolatedTmp, "pai-whisper-reinject");
+    expect(readdirSync(counterDir).length).toBe(1);
+  });
+});

package/src/hooks/ts/post-tool-use/whisper-reinject.ts

@@ -24,6 +24,7 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { tmpdir } from "node:os";
+import { isWorkerSession } from "../lib/worker-session.js";
 
 /** Stay silent below this many tool calls — a short turn has not drifted yet. */
 const QUIET_BELOW = 6;
@@ -69,6 +70,8 @@ function main(): void {
     if (raw.trim()) sessionId = (JSON.parse(raw) as { session_id?: string }).session_id ?? "";
   } catch { /* no session id — fall back to a shared counter */ }
 
+  if (isWorkerSession()) return;
+
   const n = bump(counterFile(sessionId));
   if (n < QUIET_BELOW || n % EVERY !== 0) return;
 

package/src/hooks/ts/session-start/load-project-context.ts

@@ -498,9 +498,9 @@ Session Commands:
   // 8.5. INJECT THE PAUSE CHECKPOINT
   //
   // `pai pause` writes the handover to TODO.md under `## Continue`. Until now
-  // nothing read it back: the session-commands hook only told the model to look
-  // there *if the user typed "go"*, so a resumed session started blind unless
-  // the user knew the magic word. Writing a handover nobody delivers is not a
+  // nothing read it back: CORE SKILL.md only told the model to look there *if
+  // the user typed "go"*, so a resumed session started blind unless the user
+  // knew the magic word. Writing a handover nobody delivers is not a
   // handover. Inject it, and say plainly that it is the previous session's
   // state rather than an instruction to act on.
   if (existsSync(todoPath)) {

package/src/hooks/ts/session-start/mcp-deferred-reminder.ts

@@ -11,8 +11,8 @@
  * call: see ../lib/mcp-deferred-reminder.ts for the rationale and text.
  *
  * stdout is captured by Claude Code and injected into the session context,
- * same channel as session-commands/inject-observations. Never blocks session
- * start: always exits 0.
+ * same channel as inject-observations. Never blocks session start: always
+ * exits 0.
  */
 
 import { decideMcpDeferredReminder, type ReminderHookInput } from "../lib/mcp-deferred-reminder.js";

package/src/hooks/ts/session-start/session-start-worker-guard.test.ts

@@ -15,7 +15,6 @@ describe("session-start hooks: worker sessions get no injected context", () => {
     "src/hooks/ts/session-start/load-project-context.ts",
     "src/hooks/ts/session-start/mcp-deferred-reminder.ts",
     "src/hooks/ts/session-start/post-compact-inject.ts",
-    "src/hooks/ts/session-start/session-commands.ts",
   ];
 
   function runHook(entrypoint: string, env: NodeJS.ProcessEnv): string {

package/src/hooks/ztk-auto.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+# Wrapper around ztk rewrite that auto-approves and passes through commands
+# whose output ztk would compact lossily (plain-text tools, interpreters,
+# pipelines already tailed/headed/counted, or anything requesting JSON output).
+# Changes permissionDecision from "ask" to "allow" for everything else.
+# Also handles empty responses from ztk (passthrough).
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+stdin="$(cat)"
+
+command="$(printf '%s' "$stdin" | jq -r '.tool_input.command // empty' 2>/dev/null)"
+
+if [ -n "$command" ]; then
+  decision="$(node "$script_dir/ztk-passthrough.mjs" "$command" 2>/dev/null)"
+  if [ "$decision" = "yes" ]; then
+    exit 0
+  fi
+fi
+
+result=$(printf '%s' "$stdin" | ztk rewrite 2>/dev/null)
+
+if [ -z "$result" ]; then
+  # ztk returned nothing - allow the command as-is
+  echo '{"permissionDecision":"allow"}'
+else
+  # ztk returned something - change ask to allow
+  echo "$result" | sed 's/"permissionDecision":"ask"/"permissionDecision":"allow"/'
+fi

package/src/hooks/ztk-auto.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, writeFileSync, chmodSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+// ztk-auto.sh reads the PreToolUse payload from stdin, decides whether the
+// command should bypass ztk's (lossy, for short/structured output) rewrite
+// step via ztk-passthrough.mjs, and otherwise shells out to the real `ztk`
+// binary. A pass-through decision prints nothing and exits 0 — Claude Code
+// treats a silent PreToolUse hook as "no opinion", i.e. the command runs
+// untouched. A non-pass-through decision always produces JSON output.
+describe("ztk-auto.sh", () => {
+  const SCRIPT = "src/hooks/ztk-auto.sh";
+  let fakeBinDir: string;
+
+  // Stub `ztk` so the test doesn't depend on the real binary being installed
+  // or on its exact output shape — only that ztk-auto.sh calls it and
+  // forwards its (sed-patched) output for non-pass-through commands.
+  beforeAll(() => {
+    fakeBinDir = mkdtempSync(join(tmpdir(), "ztk-auto-test-bin-"));
+    const fakeZtk = join(fakeBinDir, "ztk");
+    writeFileSync(
+      fakeZtk,
+      [
+        "#!/bin/bash",
+        "cat > /dev/null",
+        'echo \'{"permissionDecision":"ask","hookSpecificOutput":{"updatedInput":{"command":"ztk run npm test"}}}\'',
+      ].join("\n"),
+    );
+    chmodSync(fakeZtk, 0o755);
+  });
+
+  afterAll(() => {
+    rmSync(fakeBinDir, { recursive: true, force: true });
+  });
+
+  function runHook(command: string): string {
+    return execFileSync("bash", [SCRIPT], {
+      input: JSON.stringify({
+        hook_event_name: "PreToolUse",
+        tool_name: "Bash",
+        tool_input: { command },
+      }),
+      encoding: "utf8",
+      timeout: 15_000,
+      env: { ...process.env, PATH: `${fakeBinDir}:${process.env.PATH}` },
+    });
+  }
+
+  it("passes through a plain ls (empty stdout, command runs untouched)", () => {
+    expect(runHook("ls -la src")).toBe("");
+  });
+
+  it("sends an unrecognised command to ztk and rewrites it", () => {
+    const stdout = runHook("npm test");
+    expect(stdout).toContain("ztk run");
+    expect(stdout).toContain('"permissionDecision":"allow"');
+  });
+
+  it("passes through a cd-prefixed wc command", () => {
+    expect(runHook("cd /x && wc -l a")).toBe("");
+  });
+
+  it("passes through a pipeline whose last stage is tail", () => {
+    expect(runHook("cargo build 2>&1 | tail -20")).toBe("");
+  });
+
+  it("passes through a command requesting --json output", () => {
+    expect(runHook("pai worker ps --json")).toBe("");
+  });
+});

package/src/hooks/ztk-passthrough.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * ztk-passthrough — decide whether a Bash command's output should skip
+ * ztk's rewrite/compaction step.
+ *
+ * ztk compacts aggressively and is lossy for short, already-structured
+ * output: a plain `ls` came back with a file misreported as a directory,
+ * and `wc -l ... | tail -1` came back summarised instead of verbatim.
+ * Interpreters, text-processing tools, anything already piped through
+ * head/tail/wc, and anything asking for machine-readable JSON output must
+ * keep their exact stdout, so they bypass ztk entirely.
+ *
+ * Prints "yes" (pass through, skip ztk) or "no" (send to ztk) to stdout.
+ */
+
+const PASSTHROUGH_COMMANDS = new Set([
+  "ls", "wc", "echo", "printf", "pwd", "which", "whoami", "date",
+  "basename", "dirname", "readlink", "stat", "du", "df",
+  "head", "tail", "cat", "jq", "sed", "awk", "sort", "uniq", "tr", "cut",
+  "true", "test", "[",
+  "python3", "node", "bun",
+]);
+
+const LAST_STAGE_PASSTHROUGH = new Set(["head", "tail", "wc"]);
+
+const VAR_ASSIGN = /^[A-Za-z_][A-Za-z0-9_]*=(?:'[^']*'|"[^"]*"|\S*)\s+/;
+const CD_PREFIX = /^cd\s+(?:'[^']*'|"[^"]*"|\S+)\s*&&\s*/;
+const ENV_PREFIX = /^env\s+/;
+const TIMEOUT_PREFIX = /^timeout\s+\S+\s+/;
+
+/** Strip leading `cd … &&`, `env …`, `timeout N`, and variable assignments, in any order. */
+function stripLeaders(command) {
+  let cur = command.trimStart();
+  for (let i = 0; i < 20; i++) {
+    const before = cur;
+    cur = cur.replace(CD_PREFIX, "").replace(ENV_PREFIX, "").replace(TIMEOUT_PREFIX, "").replace(VAR_ASSIGN, "");
+    cur = cur.trimStart();
+    if (cur === before) break;
+  }
+  return cur;
+}
+
+function firstWord(command) {
+  return command.trim().split(/\s+/)[0] ?? "";
+}
+
+function lastPipelineStage(command) {
+  const stages = command.split("|");
+  return stages[stages.length - 1] ?? "";
+}
+
+export function shouldPassThrough(rawCommand) {
+  const command = rawCommand ?? "";
+  if (!command.trim()) return false;
+
+  if (command.includes("--output-format json") || command.includes("--json")) return true;
+
+  const lastStageFirstWord = firstWord(lastPipelineStage(command));
+  if (LAST_STAGE_PASSTHROUGH.has(lastStageFirstWord)) return true;
+
+  const stripped = stripLeaders(command);
+  const head = firstWord(stripped);
+  return PASSTHROUGH_COMMANDS.has(head);
+}
+
+function main() {
+  const command = process.argv[2] ?? "";
+  console.log(shouldPassThrough(command) ? "yes" : "no");
+}
+
+main();