brainclaw 1.7.5 → 1.9.0

package/dist/core/state.js

@@ -1,11 +1,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { ConstraintSchema, DecisionSchema, TrapSchema, HandoffSchema, PlanItemSchema } from './schema.js';
-import { ensureMemoryDir, resolveEntityDir } from './io.js';
+import { ensureMemoryDir, resolveEntityDir, writeFileAtomic } from './io.js';
 import { mutate } from './mutation-pipeline.js';
 import { commitMemoryChange } from './memory-git.js';
 import { appendEvent } from './event-log.js';
-import { loadVersionedJsonFile, saveVersionedJsonFile } from './migration.js';
+import { appendJournalRecords, resolveJournalMode, resolveCheckpointRead } from './events/journal.js';
+import { materializeStateFromCheckpoint } from './events/checkpoint.js';
+import { loadVersionedJsonFile, serializeVersionedJson, preparePersistedDocument } from './migration.js';
 import { rebuildProjectMd } from './markdown.js';
 import { refreshLiveCompanions } from '../commands/export.js';
 import { logger } from './logger.js';
@@ -102,6 +104,24 @@ export function findLoadValidationWarning(entity, id, cwd) {
 export function loadState(cwd) {
     // Load from entity-aligned directories (with legacy fallback)
     const effectiveCwd = cwd ?? process.cwd();
+    // pln#566 Inc0 s2 — checkpointRead fast path. OFF by default (dual/off mode):
+    // projection files remain the read substrate. When the capability is enabled
+    // (primary soak) AND a verified journal-derived checkpoint exists, serve from
+    // checkpoint + sealed tail instead of reading every projection file. ANY
+    // failure (no checkpoint, failed verification, replay error) falls through to
+    // the projection read below — the checkpoint is never the sole truth.
+    if (resolveCheckpointRead(effectiveCwd)) {
+        try {
+            const fast = materializeStateFromCheckpoint(effectiveCwd);
+            // Merge over emptyState so the served State carries the same envelope
+            // fields (version/write_version) a projection read produces; the
+            // checkpoint only materializes the 5 entity collections. Already sorted
+            // by projectLiveToState.
+            if (fast)
+                return { ...emptyState(), ...fast };
+        }
+        catch { /* fall through to projection read */ }
+    }
     const state = emptyState();
     state.active_constraints = loadDirectoryItems(resolveEntityDir('constraints', effectiveCwd, 'read'), ConstraintSchema, 'constraint');
     state.recent_decisions = loadDirectoryItems(resolveEntityDir('decisions', effectiveCwd, 'read'), DecisionSchema, 'decision');
@@ -116,72 +136,189 @@ export function loadState(cwd) {
     state.plan_items.sort((a, b) => a.created_at.localeCompare(b.created_at));
     return state;
 }
-function syncDirectory(dirPath, items, documentType, schema) {
-    if (!fs.existsSync(dirPath)) {
-        fs.mkdirSync(dirPath, { recursive: true });
+const persistWriteStats = { written: 0, skippedUnchanged: 0 };
+export function readPersistWriteStats() {
+    return { ...persistWriteStats };
+}
+export function resetPersistWriteStats() {
+    persistWriteStats.written = 0;
+    persistWriteStats.skippedUnchanged = 0;
+}
+/**
+ * Order-insensitive canonical form of a JSON document, for the dirty-tracking
+ * skip compare. Recursively sorts object keys; returns the raw input on parse
+ * failure so corrupt/non-JSON bytes never compare equal to a valid desired doc.
+ */
+function canonicalJson(raw) {
+    const sortKeys = (value) => {
+        if (Array.isArray(value))
+            return value.map(sortKeys);
+        if (value && typeof value === 'object') {
+            return Object.fromEntries(Object.entries(value)
+                .sort(([a], [b]) => a.localeCompare(b))
+                .map(([k, v]) => [k, sortKeys(v)]));
+        }
+        return value;
+    };
+    try {
+        return JSON.stringify(sortKeys(JSON.parse(raw)));
+    }
+    catch {
+        return raw; // unparseable → never equals a canonical desired doc
     }
-    // Write all current items
+}
+/**
+ * Pure planning pass: compute which projection files WOULD change, without
+ * writing anything. Same dirty-tracking + canonical-compare + parseable-guard
+ * logic as the old syncDirectory; only the IO is deferred to applySyncPlan.
+ */
+function planSyncDirectory(dirPath, items, documentType, schema, deleteMissing) {
+    const plan = { dirPath, writes: [], deletes: [] };
+    // Write only the items whose on-disk bytes would change (dirty-tracking,
+    // pln#543 step 3). The comparison uses the writer's own serializer so a
+    // "skip" can never diverge from what saveVersionedJsonFile would produce.
+    // Safe against trp#126: a missing/byte-different file never matches, so an
+    // in-state entity whose projection is absent/corrupt is always rewritten.
     const currentIds = new Set();
     for (const item of items) {
         currentIds.add(item.id);
         const filepath = path.join(dirPath, `${item.id}.json`);
-        saveVersionedJsonFile(documentType, filepath, item);
-    }
-    // Remove files that are no longer in the state (e.g. if deleted/pruned).
-    // CRITICAL: we must distinguish "file dropped from state intentionally" from
-    // "file silently dropped by loadDirectoryItems because its schema.parse threw".
-    // Deleting the second kind corrupts data (see trap: silent-data-loss via
-    // load-swallow + write-sync-GC). So before unlinking, we re-validate the file
-    // against the schema. Parseable + not in state = intentional remove → unlink.
-    // Unparseable = preserved, operator can inspect/repair.
-    const files = fs.readdirSync(dirPath).filter(f => f.endsWith('.json'));
+        const desired = serializeVersionedJson(documentType, item);
+        let existing;
+        try {
+            existing = fs.readFileSync(filepath, 'utf-8');
+        }
+        catch {
+            existing = undefined; // missing/unreadable → write
+        }
+        // Semantic (canonical, sorted-key) compare, not byte compare: loadState
+        // re-parses through zod which can reorder keys; a byte compare would
+        // rewrite the whole store every persist. Unparseable bytes never match
+        // → rewrite (keeps trp#126 safety).
+        if (existing !== undefined && canonicalJson(existing) === canonicalJson(desired)) {
+            persistWriteStats.skippedUnchanged += 1;
+            continue;
+        }
+        plan.writes.push({ filepath, desired, item, created: existing === undefined });
+    }
+    if (!deleteMissing)
+        return plan;
+    // Plan removals of files no longer in state. CRITICAL: distinguish an
+    // intentional drop from a file silently dropped by loadDirectoryItems on a
+    // schema.parse throw (deleting the second kind corrupts data — trp#126). Only
+    // parseable + not-in-state files are unlinked; unparseable are preserved.
+    const files = fs.existsSync(dirPath)
+        ? fs.readdirSync(dirPath).filter(f => f.endsWith('.json'))
+        : [];
     for (const file of files) {
         const id = file.replace('.json', '');
         if (currentIds.has(id))
             continue;
         const filepath = path.join(dirPath, file);
-        let parseable = false;
         try {
             schema.parse(loadVersionedJsonFile(documentType, filepath).document);
-            parseable = true;
         }
         catch {
             // Already logged by loadDirectoryItems — leave the file in place.
+            continue;
         }
-        if (parseable) {
-            fs.unlinkSync(filepath);
-        }
+        plan.deletes.push({ filepath, id });
+    }
+    return plan;
+}
+/** Apply a planned sync: the actual projection-file writes/unlinks (the IO that
+ * must happen AFTER the journal append+fsync). Returns the dirty result. */
+function applySyncPlan(plan) {
+    const result = { written: [], deleted: [] };
+    // Create the entity dir unconditionally (matches the pre-split syncDirectory,
+    // which always ensured the dir even for an empty/unchanged collection).
+    if (!fs.existsSync(plan.dirPath)) {
+        fs.mkdirSync(plan.dirPath, { recursive: true });
+    }
+    for (const { filepath, desired, item, created } of plan.writes) {
+        writeFileAtomic(filepath, desired);
+        persistWriteStats.written += 1;
+        result.written.push({ item, created });
     }
+    for (const { filepath, id } of plan.deletes) {
+        fs.unlinkSync(filepath);
+        result.deleted.push(id);
+    }
+    return result;
 }
 export function saveState(state, cwd) {
     persistState(state, cwd, { writeProjectMarkdown: false });
 }
 function persistStateUnlocked(state, cwd, options = {}) {
-    writeStateDirectories(state, cwd);
+    ensureMemoryDir(cwd);
+    const effectiveCwd = cwd ?? process.cwd();
+    // pln#566 F1 — JOURNAL BEFORE PROJECTIONS (invariant I2). Persist now runs in
+    // three ordered phases so the journal can never lag the projections: a crash
+    // mid-persist leaves the journal AHEAD (the only direction lazy-reconcile can
+    // recover), never projections ahead (which materialize/verify could not
+    // explain). Phase 1 PLAN (pure compute, no IO) → Phase 2 emit+fsync the
+    // per-entity post-images to the journal → Phase 3 APPLY projection writes.
+    const { plans, legacyDeletes, dirty } = planStateDirectories(state, effectiveCwd, options.deleteMissing ?? false);
+    emitPerEntityJournalRecords(dirty, options.eventAction, effectiveCwd);
+    faultPoint('after_journal'); // test-only: crash AFTER journal, BEFORE projections
+    applyStatePlans(plans, legacyDeletes);
+    faultPoint('after_projection'); // test-only: crash AFTER projections written
     if (options.writeProjectMarkdown ?? true) {
-        rebuildProjectMd(state, cwd);
+        rebuildProjectMd(state, effectiveCwd);
     }
+    // v1 events.jsonl: keep the coarse store event for existing consumers, but
+    // suppress its envelope-only journal dual-write — the v2 per-entity emit
+    // above is the authoritative §2.8 diff choke point.
     appendEvent({
         action: options.eventAction ?? 'update',
         item_type: 'state',
         agent: 'system',
         summary: options.eventSummary,
-    }, cwd);
-    commitMemoryChange(options.commitMessage ?? 'state update', cwd);
-    // Auto-refresh live companion files (Tier B/C agents) after state mutations.
-    // Non-fatal: failures are logged but don't break the mutation.
+    }, effectiveCwd, { journalDualWrite: false });
+    // NOTE (pln#558 step 2): the git commit and refreshLiveCompanions used to
+    // run here, INSIDE the mutation lock. A single persistState was holding
+    // the lock for >5s on Juan's machine (full-store rewrite + git add -A +
+    // git commit + live-companion refresh), which serialized every other
+    // writer. They are now invoked by persistState / mutateState AFTER the
+    // lock releases — see runPostWriteHooks below. The critical section is
+    // now writes-only; commit / companion-refresh are best-effort observers.
+}
+function runPostWriteHooks(cwd, commitMessage) {
+    // git add + git commit. Safe outside the lock because (a) git itself
+    // serializes concurrent index access via .git/index.lock, (b) the
+    // implementation already swallows failures (see memory-git.ts), and
+    // (c) the commit is an audit trail, not the data itself.
+    try {
+        commitMemoryChange(commitMessage, cwd);
+    }
+    catch { /* best-effort */ }
+    // Live companion files (Tier B/C agent surfaces). Already best-effort.
     try {
         refreshLiveCompanions(cwd);
     }
     catch { /* best-effort */ }
 }
-function cleanupLegacyDir(entityName, currentIds, cwd, documentType, schema) {
+/**
+ * Test-only crash injection (pln#566 F1). No-op unless BRAINCLAW_FAULT_POINT
+ * matches the label — then it throws, simulating a process death at that exact
+ * point in the persist pipeline so crash-ordering invariants can be tested
+ * deterministically without racing a real SIGKILL.
+ */
+function faultPoint(label) {
+    if (process.env.BRAINCLAW_FAULT_POINT === label) {
+        throw new Error(`fault-injection: crashed at "${label}" (BRAINCLAW_FAULT_POINT)`);
+    }
+}
+/**
+ * Plan (do not apply) the removal of legacy-dir orphans. Read-only: matches
+ * syncDirectory's safety condition (only parseable records absent from state
+ * are deletable; unparseable are preserved for inspection/repair). The actual
+ * unlink is deferred to applyStatePlans so it lands AFTER the journal append.
+ */
+function planCleanupLegacyDir(entityName, currentIds, cwd, documentType, schema) {
+    const out = [];
     const writeDir = resolveEntityDir(entityName, cwd, 'write');
     const readDir = resolveEntityDir(entityName, cwd, 'read');
-    // If read resolves to a different (legacy) directory, clean orphans there too.
-    // Match syncDirectory's safety condition: only delete parseable records that
-    // are absent from the current state. Schema-invalid legacy files may be drifted
-    // data that operators still need to inspect or repair.
     if (readDir !== writeDir && fs.existsSync(readDir)) {
         const files = fs.readdirSync(readDir).filter(f => f.endsWith('.json'));
         for (const file of files) {
@@ -189,51 +326,110 @@ function cleanupLegacyDir(entityName, currentIds, cwd, documentType, schema) {
             if (currentIds.has(id))
                 continue;
             const filepath = path.join(readDir, file);
-            let parseable = false;
             try {
                 schema.parse(loadVersionedJsonFile(documentType, filepath).document);
-                parseable = true;
             }
             catch {
                 logger.warn(`Preserving unparseable legacy ${entityName} file ${file}`);
                 continue;
             }
-            if (parseable) {
-                fs.unlinkSync(filepath);
-            }
+            out.push({ filepath, id }); // O3: surfaced so a delete tombstone is emitted
         }
     }
+    return out;
 }
-function writeStateDirectories(state, cwd) {
-    ensureMemoryDir(cwd);
-    const effectiveCwd = cwd ?? process.cwd();
+/**
+ * Phase 1 of persist: compute every projection change WITHOUT writing. The
+ * returned `dirty` (post-images + tombstone ids) lets the journal be emitted +
+ * fsync'd before applyStatePlans touches any file (pln#566 F1 / I2).
+ */
+function planStateDirectories(state, cwd, deleteMissing) {
     const entities = [
-        { name: 'constraints', items: state.active_constraints, docType: 'constraint', schema: ConstraintSchema },
-        { name: 'decisions', items: state.recent_decisions, docType: 'decision', schema: DecisionSchema },
-        { name: 'traps', items: state.known_traps, docType: 'trap', schema: TrapSchema },
-        { name: 'handoffs', items: state.open_handoffs, docType: 'handoff', schema: HandoffSchema },
-        { name: 'plans', items: state.plan_items, docType: 'plan', schema: PlanItemSchema },
+        { name: 'constraints', itemType: 'constraint', items: state.active_constraints, docType: 'constraint', schema: ConstraintSchema },
+        { name: 'decisions', itemType: 'decision', items: state.recent_decisions, docType: 'decision', schema: DecisionSchema },
+        { name: 'traps', itemType: 'trap', items: state.known_traps, docType: 'trap', schema: TrapSchema },
+        { name: 'handoffs', itemType: 'handoff', items: state.open_handoffs, docType: 'handoff', schema: HandoffSchema },
+        { name: 'plans', itemType: 'plan', items: state.plan_items, docType: 'plan', schema: PlanItemSchema },
     ];
-    for (const { name, items, docType, schema } of entities) {
-        const writeDir = resolveEntityDir(name, effectiveCwd, 'write');
-        syncDirectory(writeDir, items, docType, schema);
-        const currentIds = new Set(items.map(item => item.id));
-        cleanupLegacyDir(name, currentIds, effectiveCwd, docType, schema);
+    const plans = [];
+    const legacyDeletes = [];
+    const dirty = [];
+    for (const { name, itemType, items, docType, schema } of entities) {
+        const writeDir = resolveEntityDir(name, cwd, 'write');
+        const plan = planSyncDirectory(writeDir, items, docType, schema, deleteMissing);
+        plans.push(plan);
+        const deleted = plan.deletes.map(d => d.id);
+        if (deleteMissing) {
+            // O3: legacy-dir orphans must also emit a delete tombstone.
+            const legacy = planCleanupLegacyDir(name, new Set(items.map(i => i.id)), cwd, docType, schema);
+            for (const l of legacy) {
+                legacyDeletes.push(l);
+                deleted.push(l.id);
+            }
+        }
+        dirty.push({ itemType, written: plan.writes.map(w => ({ item: w.item, created: w.created })), deleted });
+    }
+    return { plans, legacyDeletes, dirty };
+}
+/** Phase 3 of persist: apply the planned projection writes/unlinks (the IO that
+ * must follow the journal append+fsync). */
+function applyStatePlans(plans, legacyDeletes) {
+    for (const plan of plans)
+        applySyncPlan(plan);
+    for (const { filepath } of legacyDeletes) {
+        try {
+            fs.unlinkSync(filepath);
+        }
+        catch { /* already gone — idempotent */ }
+    }
+}
+/**
+ * Emit one journal record per dirty entity with its full post-image
+ * (entity-state class, §2.1.1 / §2.8): the persist path is where the store's
+ * source-of-truth events are minted, because only it holds the entity docs.
+ * No-op when the journal flag is off. Failures are swallowed inside
+ * appendJournalRecords (dual mode: v1 projections remain the truth).
+ */
+function emitPerEntityJournalRecords(dirty, storeAction, cwd) {
+    if (resolveJournalMode(cwd) === 'off')
+        return;
+    const records = [];
+    for (const { itemType, written, deleted } of dirty) {
+        for (const { item, created } of written) {
+            // Post-image = the prepared document (with schema_version), so the
+            // journal record is byte-faithful to the projection: materialize can
+            // reconstruct an identical file, and verify compares like-for-like.
+            records.push({
+                action: storeAction && storeAction !== 'update' ? storeAction : (created ? 'create' : 'update'),
+                item_type: itemType,
+                item_id: item.id,
+                agent: 'system',
+                payload: preparePersistedDocument(itemType, item),
+            });
+        }
+        for (const id of deleted) {
+            records.push({ action: 'delete', item_type: itemType, item_id: id, agent: 'system' });
+        }
     }
+    if (records.length > 0)
+        appendJournalRecords(records, cwd);
 }
 export function persistState(state, cwd, options = {}) {
     const effectiveCwd = cwd ?? process.cwd();
     mutate({ cwd: effectiveCwd }, () => {
         persistStateUnlocked(state, effectiveCwd, options);
     });
+    runPostWriteHooks(effectiveCwd, options.commitMessage ?? 'state update');
 }
 export function mutateState(mutateFn, cwd, options = {}) {
     const effectiveCwd = cwd ?? process.cwd();
-    return mutate({ cwd: effectiveCwd }, () => {
+    const result = mutate({ cwd: effectiveCwd }, () => {
         const state = loadState(effectiveCwd);
-        const result = mutateFn(state);
-        persistStateUnlocked(state, effectiveCwd, options);
-        return result;
+        const value = mutateFn(state);
+        persistStateUnlocked(state, effectiveCwd, { ...options, deleteMissing: true });
+        return value;
     });
+    runPostWriteHooks(effectiveCwd, options.commitMessage ?? 'state update');
+    return result;
 }
 //# sourceMappingURL=state.js.map

package/dist/core/store-resolution.js

@@ -166,12 +166,24 @@ export function resolveProjectRef(ref, cwd = process.cwd(), storeChainOptions) {
         ?? resolveWorkspaceRoot(cwd, storeChainOptions);
     if (!wsRoot)
         return undefined;
-    // Try as absolute path
+    // The trust boundary for raw path refs is the provided cwd.  Callers in
+    // MCP context set cwd to the workspace root, so child projects resolve
+    // naturally.  Walking further up (to a user-level store at home) would
+    // allow path-injection to sibling or home stores — that is the vulnerability
+    // we are closing.  Name-based lookup below is unrestricted since it matches
+    // by project_name / project_id, not by arbitrary path.
+    const trustBoundary = path.resolve(cwd);
+    // Try as absolute path — only allowed if within the cwd boundary.
     if (path.isAbsolute(ref)) {
+        if (!isAtOrBelow(ref, trustBoundary))
+            return undefined;
         return fs.existsSync(path.join(ref, MEMORY_DIR, 'config.yaml')) ? ref : undefined;
     }
-    // Try as relative path from workspace root
-    const asPath = path.resolve(wsRoot, ref);
+    // Try as relative path resolved from the cwd boundary.
+    // Guards against ../ traversal (e.g. "../sibling-project").
+    const asPath = path.resolve(trustBoundary, ref);
+    if (!isAtOrBelow(asPath, trustBoundary))
+        return undefined;
     if (fs.existsSync(path.join(asPath, MEMORY_DIR, 'config.yaml'))) {
         return asPath;
     }
@@ -315,8 +327,10 @@ function findClosestStoreBelow(target, ceiling) {
  */
 function isAtOrBelow(dir, ancestor) {
     const rel = path.relative(ancestor, dir);
-    // If relative path starts with '..', dir is above ancestor
-    return !rel.startsWith('..');
+    // '..' prefix → dir is above ancestor. An absolute result means a different
+    // Windows drive (path.relative returns the absolute `to` path then), which is
+    // also outside the boundary — without this check `D:\evil` would pass.
+    return !rel.startsWith('..') && !path.isAbsolute(rel);
 }
 function resolveAbsoluteTargetPath(cwd, target) {
     if (path.isAbsolute(target)) {

package/dist/core/worktree.js

@@ -10,6 +10,30 @@ import { parsePorcelainZ, isSystemDirtyPath } from './dirty-scope.js';
 function gitPath(p) {
     return p.replace(/\\/g, '/');
 }
+/**
+ * can_45316d5c — sanitize a scope-derived slug into a valid git branch
+ * component (`git check-ref-format` rules). Scopes like `.github/workflows`
+ * produced `feat/.github-workflows`, which git rejects (component starting
+ * with a dot), failing the whole worktree creation.
+ *
+ * Rules covered: no leading dots/dashes, no trailing dots, no `..`, no
+ * `@{`, no control/space/`~^:?*[\\` characters, no trailing `.lock`.
+ */
+export function sanitizeBranchComponent(raw, fallback = 'scope') {
+    let slug = raw
+        .replace(/[\s~^:?*[\]\\]/g, '-') // chars forbidden by check-ref-format
+        .replace(/@\{/g, '-') // reflog syntax
+        .replace(/\.\.+/g, '.') // no double dots
+        .replace(/[^a-zA-Z0-9._-]/g, '-') // conservative whitelist for the rest
+        .replace(/-+/g, '-') // collapse dashes
+        .replace(/^[.-]+/, '') // no leading dot/dash
+        .replace(/[.-]+$/, ''); // no trailing dot/dash
+    if (/\.lock$/i.test(slug))
+        slug = slug.slice(0, -'.lock'.length);
+    if (!slug)
+        slug = fallback;
+    return slug.slice(0, 48);
+}
 /**
  * Stack marker → shared directories mapping.
  * Maven/Gradle/Cargo intentionally excluded — their dep caches live
@@ -138,7 +162,15 @@ function canonicalizeScopePath(target) {
  * project even when two projects share the same repo name.
  */
 export function worktreesBaseDir(mainWorktreePath) {
-    const hash = crypto.createHash('sha1').update(mainWorktreePath).digest('hex').slice(0, 12);
+    let stablePath = path.resolve(mainWorktreePath);
+    try {
+        stablePath = fs.realpathSync.native(stablePath);
+    }
+    catch { /* path may not exist yet; path.resolve is still deterministic */ }
+    if (process.platform === 'win32' || /^[a-zA-Z]:[\\/]/.test(mainWorktreePath)) {
+        stablePath = stablePath.toLowerCase();
+    }
+    const hash = crypto.createHash('sha1').update(stablePath).digest('hex').slice(0, 12);
     return path.join(os.homedir(), '.brainclaw', 'worktrees', hash);
 }
 /**
@@ -176,6 +208,104 @@ export function hasGitLock(cwd) {
     const lockPath = path.join(gitDir.stdout.trim(), 'index.lock');
     return fs.existsSync(lockPath);
 }
+/**
+ * True when `worktreePath` is a LINKED git worktree (created by `git worktree
+ * add`), NOT the main repository. The key invariant for pln#534's commit-on-
+ * behalf: brainclaw must NEVER commit into the integration repo, only into the
+ * isolated worktree it dispatched.
+ *
+ * Detection uses the canonical, platform-stable signal: in a linked worktree
+ * the entry at `<worktree>/.git` is a FILE (a `gitdir: …` pointer into the main
+ * repo's `.git/worktrees/<name>`), whereas the main repository's `.git` is a
+ * DIRECTORY. (An earlier implementation compared `git rev-parse
+ * --absolute-git-dir` against `--git-common-dir`, but those returned
+ * differently-normalized paths on the Windows CI runner — short 8.3 names /
+ * drive-letter case — so the main repo was misread as linked. The file-vs-dir
+ * check needs no path normalization.)
+ */
+export function isLinkedWorktree(worktreePath) {
+    if (!fs.existsSync(worktreePath))
+        return false;
+    try {
+        const dotGit = path.join(worktreePath, '.git');
+        const st = fs.statSync(dotGit);
+        // main repo → .git is a directory; linked worktree → .git is a file pointer.
+        return st.isFile();
+    }
+    catch {
+        return false; // no .git entry → not a git worktree
+    }
+}
+/**
+ * pln#534 (worktree-as-contract) — commit the uncommitted diff of a dispatched
+ * worktree ON BEHALF of a worker that cannot commit itself (a sandboxed agent
+ * whose root excludes `.git`, i.e. `dispatchCanCommit=false`). The worker's only
+ * contract is "edit files in this worktree + drop LANE-RESULT.json"; brainclaw
+ * carries the commit so the code lands on the lane branch and propagates.
+ *
+ * GUARDS (defence-in-depth, since this writes git history):
+ *   - the path must exist and be a LINKED worktree — NEVER the main repo;
+ *   - no commit when an index.lock is present (concurrent git op);
+ *   - no commit when the worktree is clean;
+ *   - all git runs are `spawnSync('git', [...])` with `-C <worktree>` semantics
+ *     (cwd-scoped, no shell) so nothing can escape the worktree.
+ * Returns a structured result instead of throwing so callers degrade gracefully.
+ */
+export function commitWorktreeOnBehalf(worktreePath, message, options = {}) {
+    if (!fs.existsSync(worktreePath)) {
+        return { committed: false, files_changed: [], reason: `worktree path does not exist: ${worktreePath}` };
+    }
+    if (!isLinkedWorktree(worktreePath)) {
+        return { committed: false, files_changed: [], reason: `refusing to commit: ${worktreePath} is not a linked git worktree (main-repo guard)` };
+    }
+    if (hasGitLock(worktreePath)) {
+        return { committed: false, files_changed: [], reason: 'git index.lock present — another git operation is in progress' };
+    }
+    const status = runGit(['status', '--porcelain'], worktreePath);
+    if (!status.ok) {
+        return { committed: false, files_changed: [], reason: `git status failed: ${status.stderr.trim()}` };
+    }
+    if (status.stdout.trim().length === 0) {
+        return { committed: false, files_changed: [], reason: 'worktree clean — nothing to commit' };
+    }
+    // Stage everything, then UNSTAGE the transient files that must never land on
+    // the lane branch: the worker's own `LANE-RESULT.json` report and any
+    // `.brainclaw/` coordination state. Committing those would pollute the branch
+    // (and master, on merge) with non-deliverable artefacts.
+    const add = runGit(['add', '-A'], worktreePath);
+    if (!add.ok) {
+        return { committed: false, files_changed: [], reason: `git add failed: ${add.stderr.trim()}` };
+    }
+    runGit(['reset', '-q', '--', 'LANE-RESULT.json', '.brainclaw', '.brainclaw-heartbeat-*'], worktreePath);
+    // The files actually staged for this commit (post-exclusion) — also the
+    // truthful files_changed report.
+    const staged = runGit(['diff', '--cached', '--name-only'], worktreePath);
+    const files = staged.stdout.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    if (files.length === 0) {
+        // Only transient files changed — nothing deliverable to commit. Restore the
+        // index so the worktree is left exactly as the worker left it.
+        runGit(['reset', '-q'], worktreePath);
+        return { committed: false, files_changed: [], reason: 'no committable changes (only transient LANE-RESULT.json / .brainclaw)' };
+    }
+    const authorName = options.authorName ?? 'brainclaw (on behalf)';
+    const authorEmail = options.authorEmail ?? 'brainclaw@on-behalf.local';
+    const commit = runGit([
+        '-c', `user.name=${authorName}`,
+        '-c', `user.email=${authorEmail}`,
+        '-c', 'commit.gpgsign=false',
+        'commit', '-m', message,
+    ], worktreePath);
+    if (!commit.ok) {
+        return { committed: false, files_changed: files, reason: `git commit failed: ${commit.stderr.trim()}` };
+    }
+    const head = runGit(['rev-parse', 'HEAD'], worktreePath);
+    return {
+        committed: true,
+        sha: head.ok ? head.stdout.trim() : undefined,
+        files_changed: files,
+        reason: 'committed on behalf of worker',
+    };
+}
 /**
  * Re-points an EXISTING worktree to `ref` via a hard reset of its checked-out
  * branch + working tree. Used when a dispatch reuses an existing claim/worktree
@@ -222,6 +352,7 @@ export function resetWorktreeToRef(worktreePath, ref) {
             const norm = p.replace(/\\/g, '/');
             return norm !== '.brainclaw-worktree.json'
                 && !norm.startsWith('.brainclaw/')
+                && !norm.startsWith('.brainclaw-heartbeat-')
                 && !norm.startsWith('.git/');
         });
         if (residue.length > 0) {
@@ -322,14 +453,42 @@ export function createWorktree(mainWorktreePath, branchName, options = {}) {
     const branchCheck = runGit(['rev-parse', '--verify', branchName], mainWorktreePath);
     const branchExists = branchCheck.ok;
     const baseRef = options.baseRef ?? 'HEAD';
-    if (branchExists && options.resetExistingBranch) {
+    if (branchExists) {
         const attachedWorktreePath = findWorktreePathForBranch(listWorktrees(mainWorktreePath), branchName);
         if (attachedWorktreePath) {
-            throw new Error(`Cannot reset branch ${branchName}: it is checked out in worktree ${attachedWorktreePath}. Remove or merge that worktree first.`);
+            throw new Error(`Cannot reuse branch ${branchName}: it is checked out in worktree ${attachedWorktreePath}. Remove or merge that worktree first.`);
+        }
+        if (options.resetExistingBranch) {
+            const reset = runGit(['branch', '--force', branchName, baseRef], mainWorktreePath);
+            if (!reset.ok) {
+                throw new Error(`git branch --force failed for ${branchName}: ${reset.stderr.trim()}`);
+            }
         }
-        const reset = runGit(['branch', '--force', branchName, baseRef], mainWorktreePath);
-        if (!reset.ok) {
-            throw new Error(`git branch --force failed for ${branchName}: ${reset.stderr.trim()}`);
+        else {
+            // can_2e282880 (worktree-as-contract at creation): a reused branch is a
+            // CONTRACT that the worker starts from the dispatch base, not from
+            // whatever stale base the branch happened to sit on (observed live: a
+            // June dispatch reused a feat/<scope> branch based on April master).
+            //   - branch has NO commits ahead of the base → silently re-point it to
+            //     the base (it carries nothing worth keeping);
+            //   - branch HAS commits not on the base → REFUSE and name them: they
+            //     are unharvested work — merging/harvesting first is the only safe
+            //     move, a silent reset would destroy it and a silent reuse would
+            //     run the worker on a stale base.
+            const ahead = runGit(['rev-list', '--count', `${baseRef}..${branchName}`], mainWorktreePath);
+            const aheadCount = ahead.ok ? parseInt(ahead.stdout.trim(), 10) : NaN;
+            if (!Number.isFinite(aheadCount)) {
+                throw new Error(`Cannot assess divergence of existing branch ${branchName} vs ${baseRef}: ${ahead.stderr.trim()}`);
+            }
+            if (aheadCount > 0) {
+                const commits = runGit(['log', '--oneline', '-n', '5', `${baseRef}..${branchName}`], mainWorktreePath);
+                throw new Error(`Refusing to reuse branch ${branchName}: it has ${aheadCount} commit(s) not on ${baseRef} (unharvested work). ` +
+                    `Harvest/merge or delete the branch first. Divergent commits:\n${commits.stdout.trim()}`);
+            }
+            const reset = runGit(['branch', '--force', branchName, baseRef], mainWorktreePath);
+            if (!reset.ok) {
+                throw new Error(`git branch --force failed for ${branchName}: ${reset.stderr.trim()}`);
+            }
         }
     }
     // Use forward-slash paths for git on Windows
@@ -719,7 +878,10 @@ export function worktreeHasOnlyBirthNoise(statusZStdout) {
     const paths = parsePorcelainZ(statusZStdout);
     return paths.every((p) => {
         const norm = p.replace(/\\/g, '/');
-        return WORKTREE_BIRTH_NOISE.has(norm) || isSystemDirtyPath(norm);
+        return WORKTREE_BIRTH_NOISE.has(norm)
+            || norm.startsWith('.brainclaw-heartbeat-') // worker liveness sentinel (sprint 1.5)
+            || norm === 'LANE-RESULT.json' // worker outcome report — harvested, never committed
+            || isSystemDirtyPath(norm);
     });
 }
 /**