@tekmidian/pai 1.0.0 → 1.0.2

package/docs/install/index.md

@@ -52,6 +52,35 @@ pai daemon logs
 pai daemon serve       # foreground, where there is no service manager
 ```
 
+### AIBroker (messaging)
+
+[AIBroker](https://github.com/mnott/AIBroker) is a separate project and PAI's messaging layer: messages between sessions, worker reports to the session that started them, terminal tab names, and WhatsApp, Telegram and PAILot. PAI runs without it, but none of these work until it is installed:
+
+```bash
+npm install -g aibroker@^0.62.4
+aibroker setup      # service, MCP registration, Claude Code hooks
+aibroker doctor     # every check green, or it says exactly what to fix
+```
+
+### Setup questions and flags
+
+`pai setup` asks the questions below in this order. Every one has a flag, so `pai setup --yes <flags>` answers any of them without a terminal; a question takes its default when the flag is absent, except one that has no default (for example the Todoist token with `--task-bus`), which needs the value as a flag or in the config. `pai setup --questions` (add `--json` for machines) prints this list for the current machine, with the value already in place where there is one. The setup skill uses it: it runs `pai setup --questions --json`, asks you in chat, then runs `pai setup --yes` with the matching flags.
+
+| Question | Flag | Default | Allowed |
+|---|---|---|---|
+| Where to store data | `--storage` | `sqlite` (`postgres` if a local one answers) | `sqlite`, `postgres` |
+| PostgreSQL connection string | `--pg-url` | the PAI Docker container | a `postgresql://` URL (implies `--storage postgres`) |
+| Embedding model | `--embedding` | `snowflake` (Ollama is used when it is faster) | `snowflake`, `bge`, `nomic`, `ollama`, `none` |
+| CLAUDE.md, PAI skill, steering rules, skill stubs, hooks, TypeScript hooks, settings.json, daemon, MCP, workers | `--no-claude-md`, `--no-skill`, `--no-steering-rules`, `--no-skill-stubs`, `--no-hooks`, `--no-ts-hooks`, `--no-settings`, `--no-daemon`, `--no-mcp`, `--no-workers` | yes | |
+| Registry scan after setup, task bus (Todoist) | `--registry-scan`, `--task-bus` | no | |
+| Assistant name | `--da-name` | `PAI` | any text |
+| Router and cockpit | `--router` / `--no-router` | enabled | |
+| Cockpit port | `--router-port` | `router.port` (8790); a port that is in use is refused and its holder shown | 1024 to 65535 |
+| Who can reach the cockpit | `--router-bind` | `loopback` | `loopback`, `tailscale`, an IPv4 address (never 0.0.0.0) |
+| AIBroker | `--no-aibroker` | installed | |
+
+The router answers land in `config.yaml` as `router.enabled`, `router.port` and `router.bind` (see [config](../config.md)). Beyond `loopback` the cockpit is reachable from other devices, behind the token in `~/.pai/router-cockpit.token`.
+
 ### Updating
 
 ```bash

package/docs/three-tier-coding.md

@@ -109,7 +109,7 @@ pai worker pending            # finished branches not merged yet
 The router serves a cockpit page at `http://127.0.0.1:8790/cockpit`. It reads the router's usage log and the worker status
 files and shows, for a chosen window:
 
-![The PAI Cockpit: cloud limits, local model status, system load and power, worker pool, tokens and cache hit ratio per provider, speed per model](images/cockpit-limits-routing.jpg)
+![The PAI Cockpit: worker runs, speed per model, and the routing of the three tiers](images/cockpit-06-runs-speed-routing.jpg)
 
 
 - **Cloud** and **Local** totals, **Providers**, **Speed per model**;

package/gemini-extension.json

@@ -2,7 +2,7 @@
   "name": "@tekmidian/pai",
   "displayName": "PAI Knowledge OS",
   "description": "Personal AI Infrastructure — persistent memory and session continuity for AI coding assistants",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "author": "Matthias Nott",
   "license": "MIT",
   "homepage": "https://github.com/mnott/PAI",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekmidian/pai",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "PAI Knowledge OS — Personal AI Infrastructure with federated memory and project management",
   "type": "module",
   "main": "dist/index.mjs",
@@ -23,10 +23,6 @@
     "gemini-extension.json",
     "statusline-command.sh",
     "tab-color-command.sh",
-    "scripts/build-hooks.mjs",
-    "scripts/build-skill-stubs.mjs",
-    "scripts/build-docs.mjs",
-    "scripts/copy-defaults.mjs",
     "docker/init.sql",
     "docker/docker-compose.yml",
     "src/hooks",

package/pai-plugin.json

@@ -3,7 +3,7 @@
   "name": "@tekmidian/pai",
   "displayName": "PAI Knowledge OS",
   "description": "Personal AI Infrastructure — persistent memory, session continuity, and knowledge graph",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "author": "Matthias Nott",
   "license": "MIT",
   "homepage": "https://github.com/mnott/PAI",

package/plugins/context-preservation/plugin.json

@@ -2,6 +2,6 @@
   "name": "pai-context-preservation",
   "displayName": "PAI Context Preservation",
   "description": "Context compression and relay across compaction cycles",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "hooks": "./hooks/hooks.json"
 }

package/plugins/core/plugin.json

@@ -2,6 +2,6 @@
   "name": "pai-core",
   "displayName": "PAI Core",
   "description": "Core memory engine, session management, and project registry",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "hooks": "./hooks/hooks.json"
 }

package/plugins/core/skills/setup/SKILL.md

@@ -9,7 +9,9 @@ description: >
 
 # PAI setup
 
-Work through the phases in order. Run the check of a phase first; if it already passes, say so and move on. Prefer `pai` commands over editing files by hand; `pai <command> --help` is the reference. Ask the user before anything that installs a service, needs an API key, or starts a large download. Never print API keys back.
+Work through the phases in order. Run the check of a phase first; if it already passes, say so and move on.
+
+**One install route, however the user started.** Whether they said "clone https://github.com/mnott/PAI and set it up for me", installed the plugin, or asked from scratch, install the same way: the released npm package (phase 2), the `pai` plugin from the marketplace (phase 2a), then `pai setup` (phase 3), which also installs AIBroker. A clone of the repository is only where these instructions came from: do not build, link or run PAI from it (that would run unreleased code). Tell the user they can delete the clone afterwards, or keep it if they want to work on PAI itself. Prefer `pai` commands over editing files by hand; `pai <command> --help` is the reference. Ask the user before anything that installs a service, needs an API key, or starts a large download — except AIBroker, which setup installs without asking because PAI's messaging depends on it. Never print API keys back.
 
 ## 1. Prerequisites
 
@@ -33,18 +35,36 @@ npm i -g @tekmidian/pai@latest   # upgrade
 
 Verify: `pai --version` prints a version and `pai more` lists commands. If `pai` is not found, add `$(npm prefix -g)/bin` to PATH in the shell profile and open a new shell.
 
+## 2a. Install the plugin
+
+Check: `claude plugin list` shows `pai`.
+
+```
+claude plugin marketplace add mnott/PAI
+claude plugin install pai@pai
+```
+
+The plugin brings PAI's skills (this one included) and keeps them current with `claude plugin update pai`. Tell the user the plugin is active from the next Claude Code session on.
+
 ## 3. Run setup
 
+Never run the interactive `pai setup` from a Bash tool: there is no terminal, so it cannot be answered. Ask the user in chat instead:
+
 ```
-pai setup            # interactive
-pai setup --yes --storage sqlite
+pai setup --questions --json
 ```
 
-Tell the user that setup also installs the background daemon as a login service (launchd on macOS, a systemd user unit on Linux), and ask before running it. Setup covers storage, search embeddings, Claude Code hooks and settings, the background daemon and the first index. It is safe to run again. `--yes` takes every default; without `--storage` it picks sqlite unless a local Postgres answers.
+It prints every question setup would ask on this machine, in order, each with `id`, `step`, `question`, `flag`, `default`, `allowed` and, where the machine already has an answer (storage, embedding, router), `current`. Ask the user those questions in chat, grouped by `step`, with each default pre-filled; accept "defaults" for all of them, and skip questions that have a `current` value unless the user wants to change it. Then run setup once with the matching flags (omit a flag to take its default):
+
+```
+pai setup --yes --storage sqlite --embedding none --router-port 9000 --router-bind loopback --no-hooks
+```
+
+Tell the user that setup also installs the background daemon as a login service (launchd on macOS, a systemd user unit on Linux) and AIBroker, and that the cockpit is reachable from other devices when its reach is not `loopback`. Setup covers storage, search embeddings, Claude Code hooks and settings, the background daemon, the router and cockpit, and the first index. It is safe to run again. Without `--storage`, `--yes` picks sqlite unless a local Postgres answers.
 
 Storage choice, ask the user:
 - **sqlite**: keyword search, no extra software. Right for most people and for small machines.
-- **postgres**: keyword plus semantic search. Needs Docker; setup starts a `pai-pgvector` container itself. On a small machine export `PAI_PG_SHARED_BUFFERS=256MB` first.
+- **postgres**: keyword plus semantic search. Needs Docker; setup starts a `pai-pgvector` container itself (or pass `--pg-url`). On a small machine export `PAI_PG_SHARED_BUFFERS=256MB` first.
 
 Verify: setup ends without an error and `pai memory search "test"` runs (it prints hits or no results, but no error; results appear once the first index is done). If it stops, fix the named cause and run `pai setup` again.
 
@@ -61,6 +81,16 @@ pai daemon restart
 
 On Linux without systemd (containers) run `pai daemon serve` in a terminal or process manager instead. If it still fails, read `pai daemon logs`.
 
+## 4a. AIBroker (messaging)
+
+Check: `aibroker doctor` exits 0. AIBroker is a separate package and PAI's messaging layer (messages between sessions, worker reports, terminal tab names, WhatsApp, Telegram, PAILot). `pai setup` installs it automatically (unless run with `--no-aibroker`); this phase only confirms it. If `aibroker` is not on the PATH or doctor fails:
+
+```
+npm install -g aibroker@^0.62.4
+aibroker setup      # service, MCP registration, Claude Code hooks
+aibroker doctor
+```
+
 ## 5. Workers: first provider
 
 Workers are Claude Code runs on a provider you choose. Setup turns them on with the built-in `anthropic` provider.
@@ -97,15 +127,16 @@ Verify: the table shows a model you have access to on every row. If a row names
 
 ## 7. Optional: router and cockpit
 
-Skip unless the user wants the cockpit. The router is off by default. It gives usage accounting, the local-model scheduler and the cockpit page.
+The router and cockpit are asked in phase 3 (`router`, `router-port`, `router-bind` in `pai setup --questions`; flags `--router`/`--no-router`, `--router-port`, `--router-bind`), so this phase only confirms them, or changes them later. Default port 8790, reach `loopback`; `tailscale` or an address makes the cockpit reachable from other devices, so say so before choosing it. It gives usage accounting, the local-model scheduler and the cockpit page.
 
 ```
-pai config set router.enabled true
+pai config set router.enabled true    # only if phase 3 left it off
+pai config set router.port 9000       # only to change the port
 pai reload
 pai router status
 ```
 
-Then open `http://127.0.0.1:8790/cockpit` in a browser.
+Then open `http://127.0.0.1:<port>/cockpit` (8790 unless changed) in a browser.
 
 Verify: `pai router status` says running and the page loads. If not, `pai router start`, then check that nothing else uses port 8790.
 
@@ -136,7 +167,7 @@ pai reload
 Report each line as pass or fail with the command output:
 
 1. `node --version` prints v20 or newer; `claude --version` prints a version
-2. `pai --version` prints a version
+2. `pai --version` prints a version; `claude plugin list` shows `pai`
 3. `pai daemon status` prints `Daemon running`
 4. `pai memory search "test"` ends without error
 5. `pai worker providers test` prints a reply and a time (`pai worker providers test anthropic` probes the local `claude` CLI; no key involved)
@@ -144,5 +175,6 @@ Report each line as pass or fail with the command output:
 7. `pai worker route` shows a model on every tier
 8. Only if phase 7 was done: `pai router status` says running and the cockpit page loads
 9. `pai` opens the session picker (Esc quits)
+10. `aibroker doctor` exits 0
 
 Details: `docs/install/index.md`, `docs/install/first-workers.md`.

package/plugins/creative/plugin.json

@@ -2,5 +2,5 @@
   "name": "pai-creative",
   "displayName": "PAI Creative Studio",
   "description": "Art direction, story explanation, voice/prosody configuration",
-  "version": "1.0.0"
+  "version": "1.0.2"
 }

package/plugins/observability/plugin.json

@@ -2,6 +2,6 @@
   "name": "pai-observability",
   "displayName": "PAI Observability Suite",
   "description": "Automatic observation capture, classification, session summaries, and search history",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "hooks": "./hooks/hooks.json"
 }

package/plugins/productivity/plugin.json

@@ -2,7 +2,7 @@
   "name": "pai-productivity",
   "displayName": "PAI Productivity",
   "description": "Planning, journaling, reviewing, research, sharing, and cross-session task routing",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "hooks": "./hooks/hooks.json",
   "skills": ["./skills/"]
 }

package/plugins/semantic-search/plugin.json

@@ -2,5 +2,5 @@
   "name": "pai-semantic-search",
   "displayName": "PAI Semantic Search",
   "description": "Vector search with pgvector, cross-encoder reranking, hybrid mode, recency boost",
-  "version": "1.0.0"
+  "version": "1.0.2"
 }

package/plugins/ui/plugin.json

@@ -2,6 +2,6 @@
   "name": "pai-ui",
   "displayName": "PAI UI Customization",
   "description": "Terminal tab titles, statusline, tab coloring, and visual customization",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "hooks": "./hooks/hooks.json"
 }

package/plugins/zettelkasten/plugin.json

@@ -2,5 +2,5 @@
   "name": "pai-zettelkasten",
   "displayName": "PAI Zettelkasten Intelligence",
   "description": "Luhmann-inspired vault intelligence with graph operations and Obsidian integration",
-  "version": "1.0.0"
+  "version": "1.0.2"
 }

package/src/hooks/session-autosave.sh

@@ -49,7 +49,14 @@ fi
 
 CLAUDE_SESSION_UUID=""
 if [ ! -t 0 ]; then
-  HOOK_INPUT=$(timeout 2 cat 2>/dev/null || true)
+  if command -v timeout &>/dev/null; then
+    HOOK_INPUT=$(timeout 2 cat 2>/dev/null || true)
+  elif command -v perl &>/dev/null; then
+    # stock macOS has no GNU timeout
+    HOOK_INPUT=$(perl -e 'alarm 2; exec "cat"' 2>/dev/null || true)
+  else
+    HOOK_INPUT=$(cat 2>/dev/null || true)
+  fi
   if [ -n "$HOOK_INPUT" ]; then
     if command -v jq &>/dev/null; then
       CLAUDE_SESSION_UUID=$(printf '%s' "$HOOK_INPUT" | jq -r '.session_id // empty' 2>/dev/null || true)

package/src/hooks/session-stop.sh

@@ -27,7 +27,14 @@ command -v "$PAI_OS" &>/dev/null || exit 0
 
 CLAUDE_SESSION_UUID=""
 if [ ! -t 0 ]; then
-  HOOK_INPUT=$(timeout 2 cat 2>/dev/null || true)
+  if command -v timeout &>/dev/null; then
+    HOOK_INPUT=$(timeout 2 cat 2>/dev/null || true)
+  elif command -v perl &>/dev/null; then
+    # stock macOS has no GNU timeout
+    HOOK_INPUT=$(perl -e 'alarm 2; exec "cat"' 2>/dev/null || true)
+  else
+    HOOK_INPUT=$(cat 2>/dev/null || true)
+  fi
   if [ -n "$HOOK_INPUT" ]; then
     if command -v jq &>/dev/null; then
       CLAUDE_SESSION_UUID=$(printf '%s' "$HOOK_INPUT" | jq -r '.session_id // empty' 2>/dev/null || true)

package/src/hooks/ts/capture-all-events.ts

@@ -6,11 +6,12 @@
  * Enhanced with agent instance metadata extraction
  */
 
-import { readFileSync, appendFileSync, mkdirSync, existsSync } from 'fs';
+import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import { historyDir, agentSessionsPath } from './lib/pai-paths.js';
 import { enrichEventWithAgentMetadata, isAgentSpawningCall } from './lib/metadata-extraction.js';
 import { isProbeSession } from './lib/project-utils.js';
+import { appendRawCapture, redactDeep } from './lib/raw-capture.js';
 import { writeJsonAtomic } from '../../config/json-store.js';
 
 interface HookEvent {
@@ -39,7 +40,7 @@ function getLocalTimestamp(): string {
 }
 
 // Get current events file path
-function getEventsFilePath(): string {
+function getEventsFilePath(): { dir: string; file: string } {
   const now = new Date();
   const tz = process.env.TIME_ZONE || Intl.DateTimeFormat().resolvedOptions().timeZone;
   const localDate = new Date(now.toLocaleString('en-US', { timeZone: tz }));
@@ -49,12 +50,7 @@ function getEventsFilePath(): string {
 
   const monthDir = join(historyDir(), 'raw-outputs', `${year}-${month}`);
 
-  // Ensure directory exists
-  if (!existsSync(monthDir)) {
-    mkdirSync(monthDir, { recursive: true });
-  }
-
-  return join(monthDir, `${year}-${month}-${day}_all-events.jsonl`);
+  return { dir: monthDir, file: join(monthDir, `${year}-${month}-${day}_all-events.jsonl`) };
 }
 
 // Session-to-agent mapping functions
@@ -162,7 +158,7 @@ async function main() {
       source_app: agentName,
       session_id: hookData.session_id || 'main',
       hook_event_type: eventType,
-      payload: hookData,
+      payload: redactDeep(hookData),
       timestamp: Date.now(),
       timestamp_local: getLocalTimestamp()
     };
@@ -177,9 +173,8 @@ async function main() {
     }
 
     // Append to events file
-    const eventsFile = getEventsFilePath();
-    const jsonLine = JSON.stringify(event) + '\n';
-    appendFileSync(eventsFile, jsonLine, 'utf-8');
+    const events = getEventsFilePath();
+    appendRawCapture(events.file, events.dir, JSON.stringify(event) + '\n');
 
   } catch (error) {
     // Silently fail - don't block Claude Code

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

@@ -30,6 +30,7 @@
  */
 
 import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { minOf } from "../../../utils/min-max.js";
 import { readTailLines, scanIncremental } from "./transcript-scan.js";
 import { paiCacheDir } from "../../../runtime-paths.js";
 import { claudeProjectsDir } from "../../../config/pai-home.js";
@@ -664,7 +665,7 @@ export function measureCompactionTrigger(
     if (admissible.length === 0) return null;
   }
 
-  const trigger = Math.min(...admissible.map((s) => s.preTokens));
+  const trigger = minOf(admissible.map((s) => s.preTokens));
   console.error(
     `[context-fill] measured trigger for ${cwd}: ${trigger} (minimum of ` +
     admissible.map((s) => `${s.preTokens}@${s.timestamp}`).join(", ") + ")"

package/src/hooks/ts/lib/path-repair.ts

@@ -339,7 +339,7 @@ function cdReason(command: string, cwd: string): string | null {
     if (existsSync(target)) continue;
     const fixed = repairValue(target, cwd, true, existsSync);
     if (!fixed) continue;
-    const next = command.replace(target, fixed);
+    const next = command.replace(target, () => fixed);
     return `Wrong path in cd: ${target}. You are already in your worktree ${cwd}; drop the cd. Corrected command: ${next}`;
   }
   return null;

package/src/hooks/ts/lib/project-utils/notify.ts

@@ -50,6 +50,7 @@ export async function sendNtfyNotification(message: string, retries = 2): Promis
     try {
       const response = await fetch(`https://ntfy.sh/${topic}`, {
         method: 'POST',
+        signal: AbortSignal.timeout(5000),
         body: message,
         headers: {
           'Title': 'Claude Code',

package/src/hooks/ts/lib/project-utils/session-notes.ts

@@ -10,6 +10,11 @@ import { join, basename } from 'path';
 // ---------------------------------------------------------------------------
 
 /** Get or create the YYYY/MM subdirectory for the current month inside notesDir. */
+/** Local YYYY-MM-DD, consistent with the month directory. */
+function localDateString(now = new Date()): string {
+  return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`;
+}
+
 function getMonthDir(notesDir: string): string {
   const now = new Date();
   const year = String(now.getFullYear());
@@ -94,7 +99,7 @@ export function getCurrentNotePath(notesDir: string): string | null {
  */
 export function createSessionNote(notesDir: string, description: string): string {
   const noteNumber = getNextNoteNumber(notesDir);
-  const date = new Date().toISOString().split('T')[0];
+  const date = localDateString();
   const monthDir = getMonthDir(notesDir);
   const filename = `${noteNumber} - ${date} - New Session.md`;
   const filepath = join(monthDir, filename);
@@ -137,7 +142,7 @@ export function appendCheckpoint(notePath: string, checkpoint: string): void {
       const noteFilename = basename(notePath);
       const numberMatch = noteFilename.match(/^(\d+)/);
       const noteNumber = numberMatch ? numberMatch[1] : '0000';
-      const date = new Date().toISOString().split('T')[0];
+      const date = localDateString();
       const content = `# Session ${noteNumber}: Recovered\n\n**Date:** ${date}\n**Status:** In Progress\n\n---\n\n## Work Done\n\n<!-- PAI will add completed work here during session -->\n\n---\n\n## Next Steps\n\n<!-- To be filled at session end -->\n\n---\n\n**Tags:** #Session\n`;
       writeFileSync(notePath, content);
       console.error(`Recreated session note: ${noteFilename}`);
@@ -325,11 +330,19 @@ export function renameSessionNote(notePath: string, meaningfulName: string): str
     .trim();
 
   const paddedNumber = noteNumber.padStart(4, '0');
-  const newFilename = `${paddedNumber} - ${date} - ${titleCaseName}.md`;
-  const newPath = join(dir, newFilename);
+  let newFilename = `${paddedNumber} - ${date} - ${titleCaseName}.md`;
+  let newPath = join(dir, newFilename);
 
   if (newFilename === oldFilename) return notePath;
 
+  // Never overwrite another note: pick a free name.
+  if (existsSync(newPath)) {
+    let n = 2;
+    while (existsSync(join(dir, `${paiNumberedBase(paddedNumber, date, titleCaseName)} (${n}).md`))) n++;
+    newFilename = `${paiNumberedBase(paddedNumber, date, titleCaseName)} (${n}).md`;
+    newPath = join(dir, newFilename);
+  }
+
   try {
     renameSync(notePath, newPath);
     console.error(`Renamed note: ${oldFilename} → ${newFilename}`);
@@ -340,6 +353,10 @@ export function renameSessionNote(notePath: string, meaningfulName: string): str
   }
 }
 
+function paiNumberedBase(num: string, date: string, name: string): string {
+  return `${num} - ${date} - ${name}`;
+}
+
 /** Update the session note's H1 title and rename the file. */
 export function updateSessionNoteTitle(notePath: string, newTitle: string): void {
   if (!existsSync(notePath)) {
@@ -380,7 +397,7 @@ export function finalizeSessionNote(notePath: string, summary: string): string {
     const completionTime = new Date().toISOString();
     content = content.replace(
       '---\n\n## Work Done',
-      `**Completed:** ${completionTime}\n\n---\n\n## Work Done`
+      () => `**Completed:** ${completionTime}\n\n---\n\n## Work Done`
     );
   }
 
@@ -388,7 +405,7 @@ export function finalizeSessionNote(notePath: string, summary: string): string {
   if (nextStepsMatch) {
     content = content.replace(
       nextStepsMatch[0],
-      `## Next Steps\n\n${summary || 'Session completed.'}`
+      () => `## Next Steps\n\n${summary || 'Session completed.'}`
     );
   }
 

package/src/hooks/ts/lib/raw-capture.ts

@@ -0,0 +1,36 @@
+/**
+ * Safe append for the history/raw-outputs JSONL captures: secrets masked,
+ * private modes, bounded size.
+ */
+
+import { appendFileSync, chmodSync, existsSync, mkdirSync, renameSync, statSync } from 'fs';
+import { maskSecrets } from './loop-guard.js';
+
+export const RAW_CAPTURE_MAX_BYTES = 10 * 1024 * 1024;
+
+/** Deep copy with every string value passed through the loop guard's secret-line masking. */
+export function redactDeep<T>(value: T): T {
+  if (typeof value === 'string') return maskSecrets(value) as unknown as T;
+  if (Array.isArray(value)) return value.map(redactDeep) as unknown as T;
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value)) out[k] = redactDeep(v);
+    return out as T;
+  }
+  return value;
+}
+
+/**
+ * Append one JSON line to `file` (directory 0700, file 0600). When the file
+ * would exceed `maxBytes` it is rotated to `<file>.1` (one backup kept).
+ */
+export function appendRawCapture(file: string, dir: string, line: string, maxBytes = RAW_CAPTURE_MAX_BYTES): void {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try {
+    if (statSync(file).size + Buffer.byteLength(line) > maxBytes) renameSync(file, `${file}.1`);
+  } catch {
+    // no file yet
+  }
+  appendFileSync(file, line, { mode: 0o600 });
+  try { chmodSync(file, 0o600); } catch { /* best effort */ }
+}

package/src/hooks/ts/lib/session-summary.ts

@@ -0,0 +1,129 @@
+/**
+ * Session summary building for the SessionEnd hook.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { historyDir } from './pai-paths.js';
+
+export async function analyzeSession(sessionId: string, yearMonth: string): Promise<any> {
+  // Try to read raw outputs for this session
+  const rawOutputsDir = join(historyDir(), 'raw-outputs', yearMonth);
+
+  let filesChanged: string[] = [];
+  let commandsExecuted: string[] = [];
+  let toolsUsed: Set<string> = new Set();
+
+  try {
+    if (existsSync(rawOutputsDir)) {
+      // Only scan today's file — not the entire month (which can be 400MB+).
+      // JSONL filenames are prefixed with YYYY-MM-DD.
+      const todayPrefix = new Date().toISOString().substring(0, 10);
+      const files = readdirSync(rawOutputsDir).filter(
+        f => f.endsWith('.jsonl') && f.startsWith(todayPrefix)
+      );
+
+      for (const file of files) {
+        const filePath = join(rawOutputsDir, file);
+        const content = readFileSync(filePath, 'utf-8');
+        const lines = content.split('\n').filter(l => l.trim());
+
+        for (const line of lines) {
+          try {
+            const entry = JSON.parse(line);
+            if (entry.session === sessionId) {
+              toolsUsed.add(entry.tool);
+
+              // Extract file changes
+              if (entry.tool === 'Edit' || entry.tool === 'Write') {
+                if (entry.input?.file_path) {
+                  filesChanged.push(entry.input.file_path);
+                }
+              }
+
+              // Extract bash commands
+              if (entry.tool === 'Bash' && entry.input?.command) {
+                commandsExecuted.push(entry.input.command);
+              }
+            }
+          } catch (e) {
+            // Skip invalid JSON lines
+          }
+        }
+      }
+    }
+  } catch (error) {
+    // Silent failure
+  }
+
+  return {
+    focus: 'general-work',
+    filesChanged: [...new Set(filesChanged)].slice(0, 10), // Unique, max 10
+    commandsExecuted: commandsExecuted.slice(0, 10), // Max 10
+    toolsUsed: Array.from(toolsUsed),
+    duration: 0 // Unknown
+  };
+}
+
+export function formatSessionDocument(timestamp: string, data: { session_id: string }, info: any): string {
+  const date = timestamp.substring(0, 10); // YYYY-MM-DD
+  const hhmmss = timestamp.substring(11); // HHMMSS
+  const time = `${hhmmss.slice(0, 2)}:${hhmmss.slice(2, 4)}:${hhmmss.slice(4, 6)}`;
+  const da = process.env.DA || 'PAI';
+
+  return `---
+capture_type: SESSION
+timestamp: ${new Date().toISOString()}
+session_id: ${data.session_id}
+duration_minutes: ${info.duration}
+executor: ${da}
+---
+
+# Session: ${info.focus}
+
+**Date:** ${date}
+**Time:** ${time}
+**Session ID:** ${data.session_id}
+
+---
+
+## Session Overview
+
+**Focus:** General development work
+**Duration:** ${info.duration > 0 ? `${info.duration} minutes` : 'Unknown'}
+
+---
+
+## Tools Used
+
+${info.toolsUsed.length > 0 ? info.toolsUsed.map((t: string) => `- ${t}`).join('\n') : '- None recorded'}
+
+---
+
+## Files Modified
+
+${info.filesChanged.length > 0 ? info.filesChanged.map((f: string) => `- \`${f}\``).join('\n') : '- None recorded'}
+
+**Total Files Changed:** ${info.filesChanged.length}
+
+---
+
+## Commands Executed
+
+${info.commandsExecuted.length > 0 ? '```bash\n' + info.commandsExecuted.join('\n') + '\n```' : 'None recorded'}
+
+---
+
+## Notes
+
+This session summary was automatically generated by the UOCS SessionEnd hook.
+
+For detailed tool outputs, see: \`${join(historyDir(), 'raw-outputs', timestamp.substring(0, 7))}/\`
+
+---
+
+**Session Outcome:** Completed
+**Generated:** ${new Date().toISOString()}
+`;
+}
+