@tekmidian/pai 0.43.0 → 0.44.0

package/docs/commands/README.md

@@ -45,16 +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, skill catalogue |
+| `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, skill catalogue |
+| [`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, skill catalogue
+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
 
@@ -92,6 +99,22 @@ Token cost of the SKILL.md / command / plugin catalogue, top entries, duplicate
 | `--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)

package/package.json

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

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/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/dist/hooks/session-commands.mjs

@@ -1,26 +0,0 @@
-#!/usr/bin/env node
-import { createRequire as __paiCreateRequire } from 'node:module';
-const require = __paiCreateRequire(import.meta.url);
-if (!process.env.PAI_QUIET_NOTICES) process.env.PAI_QUIET_NOTICES = '1';
-
-// src/hooks/ts/lib/worker-session.ts
-function isWorkerSession(env = process.env) {
-  return env.PAI_WORKER === "1";
-}
-
-// src/hooks/ts/session-start/session-commands.ts
-if (isWorkerSession()) process.exit(0);
-var commands = `<system-reminder>
-SESSION COMMANDS (always available):
-
-- "go" / "continue" / "weiter" \u2192 Read Notes/TODO.md, find ## Continue section, resume work
-- "pause session" \u2192 Save state to TODO.md, update session note, stop (no compact)
-- "end session" \u2192 Finalize note, commit if needed, start fresh next time
-- "cpp" \u2192 Release workflow: version bump \u2192 build \u2192 npm publish \u2192 git add ALL \u2192 ONE commit \u2192 git push
-
-When user says "go" with no other context, ALWAYS check TODO.md first.
-
-IMPORTANT: Full PAI context may be truncated due to size. For complete instructions (response format, workflows, principles), READ: ~/.claude/Skills/CORE/SKILL.md
-</system-reminder>`;
-console.log(commands);
-//# sourceMappingURL=session-commands.mjs.map

package/dist/hooks/session-commands.mjs.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../src/hooks/ts/lib/worker-session.ts", "../../../src/hooks/ts/session-start/session-commands.ts"],
-  "sourcesContent": ["/**\n * Worker-session detection.\n *\n * A disposable headless worker (a `claude -p` run started by an orchestrating\n * session, possibly against a different model provider with a different\n * context window) shares the project directory and the hook configuration\n * with the real session that spawned it. Left alone, the hooks treat it as a\n * session in its own right: they inject project context into it, create and\n * rename a numbered session note for it, autosave it, and enqueue a\n * model-written handover for it. Its compactions also land in the project's\n * transcript folder, where they are indistinguishable from a real session's\n * and drag the measured compaction trigger down (observed 2026-09-17: two\n * workers compacting at ~151k tokens pulled a project's trigger from ~784k\n * to ~151k, and the real session's handover fired at ~50k tokens).\n *\n * The launcher marks such sessions with `PAI_WORKER=1`. Every hook that does\n * per-session bookkeeping returns immediately when this predicate is true.\n * Deliberately NOT guarded: the security validator (a worker's shell\n * commands must still be checked) and observability capture.\n */\nexport function isWorkerSession(env: NodeJS.ProcessEnv = process.env): boolean {\n  return env.PAI_WORKER === \"1\";\n}\n", "#!/usr/bin/env node\n\n/**\n * session-commands.ts\n *\n * Tiny SessionStart hook that injects critical session commands inline.\n * Stays under 2KB to avoid persisted-output truncation.\n *\n * This runs BEFORE load-core-context so these commands are always available\n * even when the full CORE skill gets truncated.\n */\n\nimport { isWorkerSession } from \"../lib/worker-session.js\";\n\nif (isWorkerSession()) process.exit(0); // disposable worker: no per-session bookkeeping\n\nconst commands = `<system-reminder>\nSESSION COMMANDS (always available):\n\n- \"go\" / \"continue\" / \"weiter\" \u2192 Read Notes/TODO.md, find ## Continue section, resume work\n- \"pause session\" \u2192 Save state to TODO.md, update session note, stop (no compact)\n- \"end session\" \u2192 Finalize note, commit if needed, start fresh next time\n- \"cpp\" \u2192 Release workflow: version bump \u2192 build \u2192 npm publish \u2192 git add ALL \u2192 ONE commit \u2192 git push\n\nWhen user says \"go\" with no other context, ALWAYS check TODO.md first.\n\nIMPORTANT: Full PAI context may be truncated due to size. For complete instructions (response format, workflows, principles), READ: ~/.claude/Skills/CORE/SKILL.md\n</system-reminder>`;\n\nconsole.log(commands);\n"],
-  "mappings": ";;;;;;AAoBO,SAAS,gBAAgB,MAAyB,QAAQ,KAAc;AAC7E,SAAO,IAAI,eAAe;AAC5B;;;ACRA,IAAI,gBAAgB,EAAG,SAAQ,KAAK,CAAC;AAErC,IAAM,WAAW;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAajB,QAAQ,IAAI,QAAQ;",
-  "names": []
-}