tim-hooks 0.1.0-beta.0

package/README.md

@@ -0,0 +1,31 @@
+# tim-hooks
+
+Session hooks, checkpoint logic, and `.tim-project` marker handling for TIM.
+
+## Project binding: `.tim-project` vs `tim.json`
+
+**`.tim-project` is runtime state, not source.** It holds per-session fields (`session`, `exchanges`, `batch_size`, `batches_summarized`) that change every session. Do not commit it — it is listed in the repo `.gitignore`.
+
+**`tim.json` is the committed canonical default.** It contains only the stable project label, e.g. `{"project": "P0063"}`. Workers and fresh clones rely on this when no local `.tim-project` exists yet.
+
+### Resolution order
+
+1. **Nearest `.tim-project`** (walk up from cwd) — wins when present. Corrupt files are rejected (no silent fallback to `tim.json` at the same directory).
+2. **`tim.json`** (walk up) — used when no `.tim-project` exists on that chain.
+3. **`~/.tim/active-project`** or Inbox (`P0000`) — see `checkpoint.ts`.
+
+### Per-developer override
+
+Create `.tim-project` in the repo root (or any ancestor of your cwd). Session start will refresh it. To change the team default for new clones, edit committed `tim.json` instead.
+
+`validateMarkerAgainstStore` still rejects pattern-valid labels that do not exist in the TIM DB (defense against bogus labels like `P9999`).
+
+## Hook CLI resolution
+
+Hook entrypoints are relocatable. They resolve the TIM CLI in this order:
+
+1. `TIM_CLI` override.
+2. A `tim` executable on `PATH`.
+3. The sibling installed package at `tim-cli/dist/cli.js`.
+
+For example, run `bash packages/tim-hooks/scripts/tim-statusline.sh` from a source checkout, or copy/symlink the packaged scripts from any installation prefix. No repository-specific absolute path is required.

package/dist/cadence-runner.d.ts

@@ -0,0 +1,11 @@
+import type { TimStore } from 'tim-store';
+export interface CadenceResult {
+    exchangeCount: number;
+    autoCheckpoint?: boolean;
+    checkpointEntryId?: string;
+}
+/**
+ * After logging exchanges: bump marker counter, optionally auto-checkpoint.
+ */
+export declare function afterExchangeLogged(store: TimStore, sessionId: string, cwd: string): Promise<CadenceResult>;
+//# sourceMappingURL=cadence-runner.d.ts.map

package/dist/cadence-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cadence-runner.d.ts","sourceRoot":"","sources":["../src/cadence-runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAM1C,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,QAAQ,EACf,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,aAAa,CAAC,CAqBxB"}

package/dist/cadence-runner.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.afterExchangeLogged = afterExchangeLogged;
+const tim_store_1 = require("tim-store");
+const tim_core_1 = require("tim-core");
+const marker_js_1 = require("./marker.js");
+const cadence_js_1 = require("./cadence.js");
+/**
+ * After logging exchanges: bump marker counter, optionally auto-checkpoint.
+ */
+async function afterExchangeLogged(store, sessionId, cwd) {
+    const marker = (0, marker_js_1.readMarker)(cwd);
+    if (!marker) {
+        const { exchangeCount } = await (0, tim_store_1.deriveCounters)(store, sessionId);
+        return { exchangeCount };
+    }
+    const reconciled = await (0, marker_js_1.reconcileMarker)(store, cwd);
+    const everyN = (0, cadence_js_1.getCheckpointEveryN)((0, tim_core_1.loadConfig)());
+    const result = { exchangeCount: reconciled.exchanges };
+    if ((0, cadence_js_1.shouldAutoCheckpoint)(reconciled.exchanges, everyN)) {
+        const sessions = new tim_store_1.SessionManager(store);
+        const entry = await sessions.checkpoint(sessionId);
+        result.autoCheckpoint = true;
+        result.checkpointEntryId = entry.id;
+        const after = await (0, marker_js_1.reconcileMarker)(store, cwd);
+        (0, marker_js_1.writeMarker)(cwd, after);
+    }
+    return result;
+}
+//# sourceMappingURL=cadence-runner.js.map

package/dist/cadence-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cadence-runner.js","sourceRoot":"","sources":["../src/cadence-runner.ts"],"names":[],"mappings":";;AAeA,kDAyBC;AAvCD,yCAA2D;AAC3D,uCAAsC;AACtC,2CAAuE;AACvE,6CAAyE;AAQzE;;GAEG;AACI,KAAK,UAAU,mBAAmB,CACvC,KAAe,EACf,SAAiB,EACjB,GAAW;IAEX,MAAM,MAAM,GAAG,IAAA,sBAAU,EAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,IAAA,0BAAc,EAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QACjE,OAAO,EAAE,aAAa,EAAE,CAAC;IAC3B,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,IAAA,2BAAe,EAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACrD,MAAM,MAAM,GAAG,IAAA,gCAAmB,EAAC,IAAA,qBAAU,GAAE,CAAC,CAAC;IACjD,MAAM,MAAM,GAAkB,EAAE,aAAa,EAAE,UAAU,CAAC,SAAS,EAAE,CAAC;IAEtE,IAAI,IAAA,iCAAoB,EAAC,UAAU,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,CAAC;QACvD,MAAM,QAAQ,GAAG,IAAI,0BAAc,CAAC,KAAK,CAAC,CAAC;QAC3C,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;QACnD,MAAM,CAAC,cAAc,GAAG,IAAI,CAAC;QAC7B,MAAM,CAAC,iBAAiB,GAAG,KAAK,CAAC,EAAE,CAAC;QACpC,MAAM,KAAK,GAAG,MAAM,IAAA,2BAAe,EAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAChD,IAAA,uBAAW,EAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC1B,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/cadence.d.ts

@@ -0,0 +1,10 @@
+import type { TimConfigFile } from 'tim-core';
+export declare const DEFAULT_CHECKPOINT_EVERY_N = 20;
+export declare const DEFAULT_BRIEFING_MAX_TOKENS = 9000;
+export declare function getCheckpointEveryN(config: TimConfigFile): number;
+export declare function getBriefingMaxTokens(config: TimConfigFile): number;
+/** True when an auto-checkpoint should fire after this exchange count. */
+export declare function shouldAutoCheckpoint(exchangeCount: number, everyN: number): boolean;
+/** Reminder line when approaching checkpoint cadence (last 3 before N). */
+export declare function checkpointCadenceReminder(exchangeCount: number, everyN: number): string | null;
+//# sourceMappingURL=cadence.d.ts.map

package/dist/cadence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cadence.d.ts","sourceRoot":"","sources":["../src/cadence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAC7C,eAAO,MAAM,2BAA2B,OAAO,CAAC;AAEhD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAIjE;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAIlE;AAED,0EAA0E;AAC1E,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnF;AAED,2EAA2E;AAC3E,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,GACb,MAAM,GAAG,IAAI,CAOf"}

package/dist/cadence.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_BRIEFING_MAX_TOKENS = exports.DEFAULT_CHECKPOINT_EVERY_N = void 0;
+exports.getCheckpointEveryN = getCheckpointEveryN;
+exports.getBriefingMaxTokens = getBriefingMaxTokens;
+exports.shouldAutoCheckpoint = shouldAutoCheckpoint;
+exports.checkpointCadenceReminder = checkpointCadenceReminder;
+exports.DEFAULT_CHECKPOINT_EVERY_N = 20;
+exports.DEFAULT_BRIEFING_MAX_TOKENS = 9000;
+function getCheckpointEveryN(config) {
+    const n = config.checkpoint?.everyN;
+    if (typeof n === 'number' && n > 0)
+        return n;
+    return exports.DEFAULT_CHECKPOINT_EVERY_N;
+}
+function getBriefingMaxTokens(config) {
+    const n = config.briefing?.maxTokens;
+    if (typeof n === 'number' && n > 0)
+        return n;
+    return exports.DEFAULT_BRIEFING_MAX_TOKENS;
+}
+/** True when an auto-checkpoint should fire after this exchange count. */
+function shouldAutoCheckpoint(exchangeCount, everyN) {
+    return exchangeCount > 0 && exchangeCount % everyN === 0;
+}
+/** Reminder line when approaching checkpoint cadence (last 3 before N). */
+function checkpointCadenceReminder(exchangeCount, everyN) {
+    if (everyN <= 0)
+        return null;
+    const remaining = everyN - (exchangeCount % everyN);
+    if (remaining > 0 && remaining <= 3 && exchangeCount > 0) {
+        return `TIM: checkpoint in ${remaining} exchange(s) (every ${everyN})`;
+    }
+    return null;
+}
+//# sourceMappingURL=cadence.js.map

package/dist/cadence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cadence.js","sourceRoot":"","sources":["../src/cadence.ts"],"names":[],"mappings":";;;AAKA,kDAIC;AAED,oDAIC;AAGD,oDAEC;AAGD,8DAUC;AA/BY,QAAA,0BAA0B,GAAG,EAAE,CAAC;AAChC,QAAA,2BAA2B,GAAG,IAAI,CAAC;AAEhD,SAAgB,mBAAmB,CAAC,MAAqB;IACvD,MAAM,CAAC,GAAG,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC;IACpC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC;IAC7C,OAAO,kCAA0B,CAAC;AACpC,CAAC;AAED,SAAgB,oBAAoB,CAAC,MAAqB;IACxD,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC;IACrC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC;IAC7C,OAAO,mCAA2B,CAAC;AACrC,CAAC;AAED,0EAA0E;AAC1E,SAAgB,oBAAoB,CAAC,aAAqB,EAAE,MAAc;IACxE,OAAO,aAAa,GAAG,CAAC,IAAI,aAAa,GAAG,MAAM,KAAK,CAAC,CAAC;AAC3D,CAAC;AAED,2EAA2E;AAC3E,SAAgB,yBAAyB,CACvC,aAAqB,EACrB,MAAc;IAEd,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7B,MAAM,SAAS,GAAG,MAAM,GAAG,CAAC,aAAa,GAAG,MAAM,CAAC,CAAC;IACpD,IAAI,SAAS,GAAG,CAAC,IAAI,SAAS,IAAI,CAAC,IAAI,aAAa,GAAG,CAAC,EAAE,CAAC;QACzD,OAAO,sBAAsB,SAAS,uBAAuB,MAAM,GAAG,CAAC;IACzE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/checkpoint.d.ts

@@ -0,0 +1,56 @@
+import type { Entry } from 'tim-core';
+import type { HooksConfig } from 'tim-core';
+import { type Summarizer, type TimStore } from 'tim-store';
+import { type HookEnv } from './hooks.js';
+export interface SessionEndOptions {
+    summarize?: Summarizer;
+    hooksConfig?: HooksConfig;
+    env?: HookEnv;
+}
+export interface SessionStartResult {
+    session: Entry;
+    project: Entry | null;
+    /** Optional briefing supplement (delta, update check, …). */
+    briefing?: string;
+}
+/** Resolve active project label from TIM_PROJECT env or ~/.tim/active-project. */
+export declare function getActiveProjectLabel(): string | null;
+/**
+ * Resolve the active project from a .tim-project marker in cwd ONLY.
+ *
+ * No walk-up. No parent traversal. This is the Auto-Load Hook contract:
+ * a session binds to a project only if the marker is in the directory the
+ * user explicitly invoked the harness from. Walking up to a parent has
+ * caused repeated cross-project binding bugs (Worker A→B→C in 2 days);
+ * cwd-only is the same pattern Hermes statusline uses after the 133c5abd
+ * fix in its-over-9k, kept consistent here.
+ *
+ * Falls back to:
+ *  - readMarker(cwd) which checks .tim-project and then tim.json
+ *  - validateMarkerAgainstStore which gates the project label against the DB
+ *
+ * Returns the project label, or null when no cwd marker exists, the marker
+ * is corrupt, or the project does not exist in the DB.
+ */
+export declare function resolveActiveProjectFromCwd(cwd: string, store: TimStore): Promise<string | null>;
+/** Load project entry by hmem-style label (e.g. P0062) when configured. */
+export declare function loadProjectContext(store: TimStore): Promise<Entry | null>;
+export declare function runCheckpoint(store: TimStore, sessionId: string, opts?: {
+    summarize?: Summarizer;
+    runDecay?: boolean;
+    handoffNote?: string;
+}): Promise<Entry>;
+export declare function runSessionStart(store: TimStore, params: {
+    sessionId: string;
+    agentName: string;
+    cwd: string;
+    harness: string;
+    hooksConfig?: HooksConfig;
+    projectId?: string;
+    batchSize?: number;
+    tool?: string;
+    model?: string;
+    taskSummary?: string;
+}): Promise<SessionStartResult>;
+export declare function runSessionEnd(store: TimStore, sessionId: string, opts?: SessionEndOptions): Promise<Entry>;
+//# sourceMappingURL=checkpoint.d.ts.map

package/dist/checkpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../src/checkpoint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAS5C,OAAO,EAKL,KAAK,UAAU,EACf,KAAK,QAAQ,EACd,MAAM,WAAW,CAAC;AACnB,OAAO,EAAsB,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAc9D,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,EAAE,UAAU,CAAC;IACvB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,KAAK,CAAC;IACf,OAAO,EAAE,KAAK,GAAG,IAAI,CAAC;IACtB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,kFAAkF;AAClF,wBAAgB,qBAAqB,IAAI,MAAM,GAAG,IAAI,CASrD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,2BAA2B,CAC/C,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,QAAQ,GACd,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAKxB;AAED,2EAA2E;AAC3E,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAI/E;AAyED,wBAAsB,aAAa,CACjC,KAAK,EAAE,QAAQ,EACf,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9E,OAAO,CAAC,KAAK,CAAC,CAGhB;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,QAAQ,EACf,MAAM,EAAE;IACN,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GACA,OAAO,CAAC,kBAAkB,CAAC,CAyD7B;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,QAAQ,EACf,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE,iBAAsB,GAC3B,OAAO,CAAC,KAAK,CAAC,CA2BhB"}

package/dist/checkpoint.js

@@ -0,0 +1,232 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getActiveProjectLabel = getActiveProjectLabel;
+exports.resolveActiveProjectFromCwd = resolveActiveProjectFromCwd;
+exports.loadProjectContext = loadProjectContext;
+exports.runCheckpoint = runCheckpoint;
+exports.runSessionStart = runSessionStart;
+exports.runSessionEnd = runSessionEnd;
+const tim_core_1 = require("tim-core");
+const cadence_js_1 = require("./cadence.js");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const tim_store_1 = require("tim-store");
+const hooks_js_1 = require("./hooks.js");
+const delta_js_1 = require("./delta.js");
+const update_check_js_1 = require("./update-check.js");
+const marker_js_1 = require("./marker.js");
+const phantom_recovery_js_1 = require("./phantom-recovery.js");
+const session_hooks_js_1 = require("./session-hooks.js");
+/** Resolve active project label from TIM_PROJECT env or ~/.tim/active-project. */
+function getActiveProjectLabel() {
+    const fromEnv = process.env.TIM_PROJECT?.trim();
+    if (fromEnv)
+        return fromEnv;
+    const activeFile = path.join((0, tim_core_1.getTimDir)(), 'active-project');
+    if (!fs.existsSync(activeFile))
+        return null;
+    const label = fs.readFileSync(activeFile, 'utf8').trim();
+    return label || null;
+}
+/**
+ * Resolve the active project from a .tim-project marker in cwd ONLY.
+ *
+ * No walk-up. No parent traversal. This is the Auto-Load Hook contract:
+ * a session binds to a project only if the marker is in the directory the
+ * user explicitly invoked the harness from. Walking up to a parent has
+ * caused repeated cross-project binding bugs (Worker A→B→C in 2 days);
+ * cwd-only is the same pattern Hermes statusline uses after the 133c5abd
+ * fix in its-over-9k, kept consistent here.
+ *
+ * Falls back to:
+ *  - readMarker(cwd) which checks .tim-project and then tim.json
+ *  - validateMarkerAgainstStore which gates the project label against the DB
+ *
+ * Returns the project label, or null when no cwd marker exists, the marker
+ * is corrupt, or the project does not exist in the DB.
+ */
+async function resolveActiveProjectFromCwd(cwd, store) {
+    const located = (0, marker_js_1.discoverMarker)(cwd, marker_js_1.CWD_ONLY_MARKER_DISCOVERY_POLICY);
+    if (!located)
+        return null;
+    const validated = await (0, marker_js_1.validateMarkerAgainstStore)(located.marker, store);
+    return validated?.project ?? null;
+}
+/** Load project entry by hmem-style label (e.g. P0062) when configured. */
+async function loadProjectContext(store) {
+    const label = getActiveProjectLabel();
+    if (!label)
+        return null;
+    return store.read(label);
+}
+async function resolveSessionProjectId(store, cwd, explicitProjectId) {
+    if (explicitProjectId) {
+        // Validate explicit project ids against the DB so a hand-edited
+        // `--project=P9999` (or a botched upstream commit) can't smuggle
+        // a bogus label into the marker. The Inbox (P0000) is exempt —
+        // it's a system project that tim-store.ensureInboxProject()
+        // materializes on first use. This closes the second half of the
+        // P9999 bug: even if the on-disk marker was repaired, an
+        // explicit override could re-poison the file.
+        if (explicitProjectId !== 'P0000') {
+            const resolved = await store.resolveProjectLabel(explicitProjectId);
+            if (resolved.status === 'found')
+                return resolved.label;
+            if (resolved.status === 'not_found') {
+                throw new Error(`Project not found: ${explicitProjectId}. Use tim_load_project to pick a real project.`);
+            }
+            throw new Error(`Ambiguous project label: ${explicitProjectId} matches ${resolved.labels.join(', ')}.`);
+        }
+        return explicitProjectId;
+    }
+    const located = (0, marker_js_1.discoverMarker)(cwd, marker_js_1.CWD_ONLY_MARKER_DISCOVERY_POLICY);
+    if (located) {
+        const validated = await (0, marker_js_1.validateMarkerAgainstStore)(located.marker, store);
+        if (validated)
+            return validated.project;
+        const recovered = await (0, phantom_recovery_js_1.repairPhantomProjectBinding)(store, located.dir);
+        if (recovered) {
+            if (store.getDatabasePath() !== ':memory:') {
+                (0, marker_js_1.writeMarker)(located.dir, (0, phantom_recovery_js_1.markerWithRepairedProject)(located.marker, recovered));
+            }
+            return recovered;
+        }
+        await (0, tim_store_1.ensureInboxProject)(store);
+        return tim_store_1.INBOX_PROJECT_LABEL;
+    }
+    const active = getActiveProjectLabel();
+    if (active) {
+        const validated = await (0, marker_js_1.validateMarkerAgainstStore)({
+            version: 2,
+            project: active,
+            session: '',
+            exchanges: 0,
+            batch_size: 5,
+            batches_summarized: 0,
+        }, store);
+        if (validated)
+            return validated.project;
+    }
+    const auto = await (0, tim_store_1.ensureProjectForPath)(store, cwd);
+    if (auto)
+        return auto.label;
+    await (0, tim_store_1.ensureInboxProject)(store);
+    return tim_store_1.INBOX_PROJECT_LABEL;
+}
+async function runCheckpoint(store, sessionId, opts = {}) {
+    const sessions = new tim_store_1.SessionManager(store);
+    return sessions.checkpoint(sessionId, opts);
+}
+async function runSessionStart(store, params) {
+    const sessions = new tim_store_1.SessionManager(store);
+    const projectId = await resolveSessionProjectId(store, params.cwd, params.projectId);
+    const session = await sessions.startProjectSession({
+        sessionId: params.sessionId,
+        projectId,
+        agentName: params.agentName,
+        cwd: params.cwd,
+        harness: params.harness,
+        batchSize: params.batchSize,
+    });
+    if (store.getDatabasePath() !== ':memory:') {
+        (0, marker_js_1.writeMarker)(params.cwd, {
+            project: projectId,
+            session: params.sessionId,
+            exchanges: 0,
+            batch_size: typeof session.metadata.batch_size === 'number'
+                ? session.metadata.batch_size
+                : 5,
+            batches_summarized: 0,
+            version: 2,
+        });
+    }
+    await (0, hooks_js_1.runConfiguredHooks)('sessionStart', params.hooksConfig, {
+        TIM_SESSION_ID: params.sessionId,
+        TIM_CWD: params.cwd,
+        TIM_AGENT: params.agentName,
+        TIM_HARNESS: params.harness,
+        TIM_PROJECT: projectId,
+    });
+    const project = await store.read(projectId);
+    let briefing;
+    const briefingParts = [];
+    if (projectId !== tim_store_1.INBOX_PROJECT_LABEL) {
+        const delta = await (0, delta_js_1.getDeltaBriefing)(store, projectId, {
+            sessionId: params.sessionId,
+        });
+        if (delta)
+            briefingParts.push(delta);
+    }
+    const updateLine = await (0, update_check_js_1.getUpdateCheckLineBriefing)();
+    if (updateLine)
+        briefingParts.push(updateLine);
+    const marker = (0, marker_js_1.readMarker)(params.cwd);
+    if (marker && marker.exchanges > 0) {
+        const everyN = (0, cadence_js_1.getCheckpointEveryN)((0, tim_core_1.loadConfig)());
+        const reminder = (0, cadence_js_1.checkpointCadenceReminder)(marker.exchanges, everyN);
+        if (reminder)
+            briefingParts.push(reminder);
+    }
+    if (briefingParts.length > 0)
+        briefing = briefingParts.join('\n');
+    return { session, project, briefing };
+}
+async function runSessionEnd(store, sessionId, opts = {}) {
+    const cwd = opts.env?.TIM_CWD ?? process.cwd();
+    const env = {
+        TIM_SESSION_ID: sessionId,
+        TIM_CWD: cwd,
+        ...opts.env,
+    };
+    await (0, hooks_js_1.runConfiguredHooks)('sessionEnd', opts.hooksConfig, env);
+    await (0, session_hooks_js_1.onSessionStop)(store, cwd);
+    // Periodically regenerate the project-level summary (every Nth session).
+    // Fire-and-forget — must never block or fail the session-end hook.
+    try {
+        const config = (0, tim_core_1.loadConfig)();
+        const threshold = config.projectSummary?.sessions_threshold ?? session_hooks_js_1.DEFAULT_PROJECT_SUMMARY_THRESHOLD;
+        const cwdLabel = await resolveActiveProjectFromCwd(cwd, store);
+        const label = cwdLabel ?? getActiveProjectLabel();
+        await (0, session_hooks_js_1.maybeSpawnProjectSummary)(store, cwd, label, { threshold });
+    }
+    catch {
+        /* non-critical */
+    }
+    return runCheckpoint(store, sessionId, {
+        summarize: opts.summarize,
+    });
+}
+//# sourceMappingURL=checkpoint.js.map

package/dist/checkpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.js","sourceRoot":"","sources":["../src/checkpoint.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8CA,sDASC;AAmBD,kEAQC;AAGD,gDAIC;AAyED,sCAOC;AAED,0CAuEC;AAED,sCA+BC;AAjRD,uCAAiD;AACjD,6CAIsB;AACtB,uCAAyB;AACzB,2CAA6B;AAC7B,yCAOmB;AACnB,yCAA8D;AAC9D,yCAA8C;AAC9C,uDAA+D;AAC/D,2CAAoI;AACpI,+DAG+B;AAC/B,yDAI4B;AAe5B,kFAAkF;AAClF,SAAgB,qBAAqB;IACnC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC;IAChD,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAE5B,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,IAAA,oBAAS,GAAE,EAAE,gBAAgB,CAAC,CAAC;IAC5D,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IAE5C,MAAM,KAAK,GAAG,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;IACzD,OAAO,KAAK,IAAI,IAAI,CAAC;AACvB,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACI,KAAK,UAAU,2BAA2B,CAC/C,GAAW,EACX,KAAe;IAEf,MAAM,OAAO,GAAG,IAAA,0BAAc,EAAC,GAAG,EAAE,4CAAgC,CAAC,CAAC;IACtE,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,MAAM,SAAS,GAAG,MAAM,IAAA,sCAA0B,EAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC1E,OAAO,SAAS,EAAE,OAAO,IAAI,IAAI,CAAC;AACpC,CAAC;AAED,2EAA2E;AACpE,KAAK,UAAU,kBAAkB,CAAC,KAAe;IACtD,MAAM,KAAK,GAAG,qBAAqB,EAAE,CAAC;IACtC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED,KAAK,UAAU,uBAAuB,CACpC,KAAe,EACf,GAAW,EACX,iBAA0B;IAE1B,IAAI,iBAAiB,EAAE,CAAC;QACtB,gEAAgE;QAChE,iEAAiE;QACjE,+DAA+D;QAC/D,4DAA4D;QAC5D,gEAAgE;QAChE,yDAAyD;QACzD,8CAA8C;QAC9C,IAAI,iBAAiB,KAAK,OAAO,EAAE,CAAC;YAClC,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,mBAAmB,CAAC,iBAAiB,CAAC,CAAC;YACpE,IAAI,QAAQ,CAAC,MAAM,KAAK,OAAO;gBAAE,OAAO,QAAQ,CAAC,KAAK,CAAC;YACvD,IAAI,QAAQ,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;gBACpC,MAAM,IAAI,KAAK,CACb,sBAAsB,iBAAiB,gDAAgD,CACxF,CAAC;YACJ,CAAC;YACD,MAAM,IAAI,KAAK,CACb,4BAA4B,iBAAiB,YAAY,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACvF,CAAC;QACJ,CAAC;QACD,OAAO,iBAAiB,CAAC;IAC3B,CAAC;IAED,MAAM,OAAO,GAAG,IAAA,0BAAc,EAAC,GAAG,EAAE,4CAAgC,CAAC,CAAC;IACtE,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,SAAS,GAAG,MAAM,IAAA,sCAA0B,EAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAC1E,IAAI,SAAS;YAAE,OAAO,SAAS,CAAC,OAAO,CAAC;QAExC,MAAM,SAAS,GAAG,MAAM,IAAA,iDAA2B,EAAC,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;QACxE,IAAI,SAAS,EAAE,CAAC;YACd,IAAI,KAAK,CAAC,eAAe,EAAE,KAAK,UAAU,EAAE,CAAC;gBAC3C,IAAA,uBAAW,EACT,OAAO,CAAC,GAAG,EACX,IAAA,+CAAyB,EAAC,OAAO,CAAC,MAAM,EAAE,SAAS,CAAC,CACrD,CAAC;YACJ,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,IAAA,8BAAkB,EAAC,KAAK,CAAC,CAAC;QAChC,OAAO,+BAAmB,CAAC;IAC7B,CAAC;IAED,MAAM,MAAM,GAAG,qBAAqB,EAAE,CAAC;IACvC,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,SAAS,GAAG,MAAM,IAAA,sCAA0B,EAChD;YACE,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,MAAM;YACf,OAAO,EAAE,EAAE;YACX,SAAS,EAAE,CAAC;YACZ,UAAU,EAAE,CAAC;YACb,kBAAkB,EAAE,CAAC;SACtB,EACD,KAAK,CACN,CAAC;QACF,IAAI,SAAS;YAAE,OAAO,SAAS,CAAC,OAAO,CAAC;IAC1C,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,IAAA,gCAAoB,EAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACpD,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC;IAE5B,MAAM,IAAA,8BAAkB,EAAC,KAAK,CAAC,CAAC;IAChC,OAAO,+BAAmB,CAAC;AAC7B,CAAC;AAEM,KAAK,UAAU,aAAa,CACjC,KAAe,EACf,SAAiB,EACjB,OAA6E,EAAE;IAE/E,MAAM,QAAQ,GAAG,IAAI,0BAAc,CAAC,KAAK,CAAC,CAAC;IAC3C,OAAO,QAAQ,CAAC,UAAU,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;AAC9C,CAAC;AAEM,KAAK,UAAU,eAAe,CACnC,KAAe,EACf,MAWC;IAED,MAAM,QAAQ,GAAG,IAAI,0BAAc,CAAC,KAAK,CAAC,CAAC;IAC3C,MAAM,SAAS,GAAG,MAAM,uBAAuB,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;IAErF,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,mBAAmB,CAAC;QACjD,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,SAAS;QACT,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,SAAS,EAAE,MAAM,CAAC,SAAS;KAC5B,CAAC,CAAC;IAEH,IAAI,KAAK,CAAC,eAAe,EAAE,KAAK,UAAU,EAAE,CAAC;QAC3C,IAAA,uBAAW,EAAC,MAAM,CAAC,GAAG,EAAE;YACtB,OAAO,EAAE,SAAS;YAClB,OAAO,EAAE,MAAM,CAAC,SAAS;YACzB,SAAS,EAAE,CAAC;YACZ,UAAU,EAAE,OAAO,OAAO,CAAC,QAAQ,CAAC,UAAU,KAAK,QAAQ;gBACzD,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAC7B,CAAC,CAAC,CAAC;YACL,kBAAkB,EAAE,CAAC;YACrB,OAAO,EAAE,CAAC;SACX,CAAC,CAAC;IACL,CAAC;IAED,MAAM,IAAA,6BAAkB,EAAC,cAAc,EAAE,MAAM,CAAC,WAAW,EAAE;QAC3D,cAAc,EAAE,MAAM,CAAC,SAAS;QAChC,OAAO,EAAE,MAAM,CAAC,GAAG;QACnB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,WAAW,EAAE,MAAM,CAAC,OAAO;QAC3B,WAAW,EAAE,SAAS;KACvB,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAE5C,IAAI,QAA4B,CAAC;IACjC,MAAM,aAAa,GAAa,EAAE,CAAC;IACnC,IAAI,SAAS,KAAK,+BAAmB,EAAE,CAAC;QACtC,MAAM,KAAK,GAAG,MAAM,IAAA,2BAAgB,EAAC,KAAK,EAAE,SAAS,EAAE;YACrD,SAAS,EAAE,MAAM,CAAC,SAAS;SAC5B,CAAC,CAAC;QACH,IAAI,KAAK;YAAE,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACvC,CAAC;IACD,MAAM,UAAU,GAAG,MAAM,IAAA,4CAA0B,GAAE,CAAC;IACtD,IAAI,UAAU;QAAE,aAAa,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAE/C,MAAM,MAAM,GAAG,IAAA,sBAAU,EAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,MAAM,IAAI,MAAM,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,IAAA,gCAAmB,EAAC,IAAA,qBAAU,GAAE,CAAC,CAAC;QACjD,MAAM,QAAQ,GAAG,IAAA,sCAAyB,EAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QACrE,IAAI,QAAQ;YAAE,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC7C,CAAC;IAED,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC;QAAE,QAAQ,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAElE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AACxC,CAAC;AAEM,KAAK,UAAU,aAAa,CACjC,KAAe,EACf,SAAiB,EACjB,OAA0B,EAAE;IAE5B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAC/C,MAAM,GAAG,GAAY;QACnB,cAAc,EAAE,SAAS;QACzB,OAAO,EAAE,GAAG;QACZ,GAAG,IAAI,CAAC,GAAG;KACZ,CAAC;IAEF,MAAM,IAAA,6BAAkB,EAAC,YAAY,EAAE,IAAI,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;IAE9D,MAAM,IAAA,gCAAa,EAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAEhC,yEAAyE;IACzE,mEAAmE;IACnE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAA,qBAAU,GAAE,CAAC;QAC5B,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,EAAE,kBAAkB,IAAI,oDAAiC,CAAC;QACjG,MAAM,QAAQ,GAAG,MAAM,2BAA2B,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC/D,MAAM,KAAK,GAAG,QAAQ,IAAI,qBAAqB,EAAE,CAAC;QAClD,MAAM,IAAA,2CAAwB,EAAC,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IACnE,CAAC;IAAC,MAAM,CAAC;QACP,kBAAkB;IACpB,CAAC;IAED,OAAO,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE;QACrC,SAAS,EAAE,IAAI,CAAC,SAAS;KAC1B,CAAC,CAAC;AACL,CAAC"}

package/dist/claude-stop.d.ts

@@ -0,0 +1,32 @@
+import type { TimStore } from 'tim-store';
+import { type CadenceResult } from './cadence-runner.js';
+export declare const MAX_TRANSCRIPT_BYTES: number;
+export declare const MAX_EXCHANGE_CHARS: number;
+export interface ClaudeStopPayload {
+    session_id: string;
+    transcript_path: string;
+    cwd?: string;
+    stop_hook_active?: boolean;
+    [key: string]: unknown;
+}
+export interface ClaudeStopResult extends Partial<CadenceResult> {
+    logged: boolean;
+    duplicate?: boolean;
+}
+interface TranscriptTurn {
+    user: string;
+    assistant: string;
+    identity: string;
+}
+/**
+ * Read a Claude Code transcript JSONL and return the last genuine user/assistant turn.
+ * Skips isMeta, tool-only assistants, malformed lines, and files over the byte bound.
+ */
+export declare function readLastExchange(transcriptPath: string, maxBytes?: number): TranscriptTurn | null;
+export declare function runClaudeStop(store: TimStore, payload: ClaudeStopPayload, options: {
+    cwd: string;
+}): Promise<ClaudeStopResult>;
+/** Test helper: expose counters after stop logging. */
+export declare function stopExchangeCount(store: TimStore, sessionId: string): Promise<number>;
+export {};
+//# sourceMappingURL=claude-stop.d.ts.map

package/dist/claude-stop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-stop.d.ts","sourceRoot":"","sources":["../src/claude-stop.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAG9E,eAAO,MAAM,oBAAoB,QAAc,CAAC;AAChD,eAAO,MAAM,kBAAkB,QAAY,CAAC;AAE5C,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAiB,SAAQ,OAAO,CAAC,aAAa,CAAC;IAC9D,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAoDD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,cAAc,EAAE,MAAM,EACtB,QAAQ,SAAuB,GAC9B,cAAc,GAAG,IAAI,CAwDvB;AA4BD,wBAAsB,aAAa,CACjC,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GACvB,OAAO,CAAC,gBAAgB,CAAC,CA6B3B;AAED,uDAAuD;AACvD,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE3F"}