brainclaw 1.8.0 → 1.9.0

package/dist/commands/memory.js

@@ -1,6 +1,6 @@
 import { loadConfig } from '../core/config.js';
 import { memoryExists } from '../core/io.js';
-import { loadState, persistState } from '../core/state.js';
+import { loadState, persistState, mutateState } from '../core/state.js';
 import { scanText } from '../core/security.js';
 import { validateCliInput } from '../core/input-validation.js';
 import { resolveTargetStore } from '../core/store-resolution.js';
@@ -229,26 +229,30 @@ function runMemoryDelete(id, cwd) {
         console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
         process.exit(1);
     }
-    const state = loadState(cwd);
-    const arrays = [
-        state.recent_decisions,
-        state.active_constraints,
-        state.known_traps,
-        state.open_handoffs,
-    ];
+    // mutateState (RMW under the store lock + deleteMissing) so the entity file
+    // is actually unlinked — persistState alone no longer deletes absent records.
     let deleted;
-    for (const items of arrays) {
-        const index = items.findIndex((item) => item.id === id || item.short_label === id);
-        if (index >= 0) {
-            [deleted] = items.splice(index, 1);
-            break;
-        }
+    try {
+        deleted = mutateState((state) => {
+            const arrays = [
+                state.recent_decisions,
+                state.active_constraints,
+                state.known_traps,
+                state.open_handoffs,
+            ];
+            for (const items of arrays) {
+                const index = items.findIndex((item) => item.id === id || item.short_label === id);
+                if (index >= 0) {
+                    return items.splice(index, 1)[0];
+                }
+            }
+            throw new Error(`Memory item '${id}' not found.`);
+        }, cwd);
     }
-    if (!deleted) {
-        console.error(`Error: Memory item '${id}' not found.`);
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
         process.exit(1);
     }
-    persistState(state, cwd);
     console.log(`✔ Memory item deleted: [${deleted.id}] ${deleted.text}`);
 }
 function collectMemoryItems(state) {

package/dist/commands/migrate.js

@@ -1,21 +1,69 @@
-import { loadState, persistState } from '../core/state.js';
+import { loadState, mutateState } from '../core/state.js';
 import { memoryExists } from '../core/io.js';
 import { resolveTargetStore } from '../core/store-resolution.js';
 import { appendAuditEntry } from '../core/audit.js';
 import { resolveCurrentAgentName } from '../core/agent-registry.js';
+import { loadConfig, saveConfig } from '../core/config.js';
+import { runGenesisMigration, runRegistryGenesisSupplement } from '../core/events/genesis.js';
 export function runMigrate(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     if (!memoryExists(cwd)) {
         console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
         process.exit(1);
     }
-    if (options.promoteMachineItems) {
+    if (options.enableJournal) {
+        enableJournalMode(cwd, options.dryRun ?? false);
+    }
+    else if (options.promoteMachineItems) {
         promoteMachineItems(cwd, options.dryRun ?? false);
     }
     else {
-        console.log('Usage: brainclaw migrate --promote-machine-items [--dry-run]');
-        console.log('');
-        console.log('Moves items tagged scope:machine from project store to user store (~/.brainclaw/).');
+        console.log('Usage:');
+        console.log('  brainclaw migrate --promote-machine-items [--dry-run]');
+        console.log('      Move items tagged scope:machine from project store to user store (~/.brainclaw/).');
+        console.log('  brainclaw migrate --enable-journal [--dry-run]');
+        console.log('      Turn on the event journal (mode=dual) for this existing store and backfill it (pln#567).');
+    }
+}
+/**
+ * pln#567 (decision A+D) — enable the event journal on an EXISTING store. New
+ * stores get this from `init`; this is the explicit opt-in for stores created
+ * before the cutover. Sets `store.journal.mode=dual` (an explicit user action,
+ * so it overrides a prior off) THEN runs genesis so the journal carries the
+ * full history rather than only mutations from now on (idempotent — a second
+ * run no-ops once a genesis note exists).
+ */
+function enableJournalMode(cwd, dryRun) {
+    const config = loadConfig(cwd);
+    const currentMode = config.store?.journal?.mode ?? 'unset';
+    if (dryRun) {
+        const planned = runGenesisMigration({ cwd, dryRun: true });
+        const plannedRegistry = runRegistryGenesisSupplement({ cwd, dryRun: true });
+        console.log(`(dry-run) Would set store.journal.mode=dual (currently ${currentMode}), backfill ${planned.backfilled} memory entit(y/ies) and ${plannedRegistry.backfilled} registry entit(y/ies), and emit the registry cutover marker (pln#568).`);
+        return;
+    }
+    config.store = { ...config.store, journal: { ...config.store?.journal, mode: 'dual' } };
+    saveConfig(config, cwd);
+    // Config is written first so genesis (which checks resolveJournalMode) seeds
+    // under dual and the journal stays consistent with subsequent dual-writes.
+    const result = runGenesisMigration({ cwd });
+    if (result.status === 'already_present') {
+        console.log(`✔ store.journal.mode=dual. Memory journal already seeded (genesis present).`);
+    }
+    else {
+        console.log(`✔ store.journal.mode=dual and seeded: ${result.backfilled} memory entit(y/ies) backfilled across ${Object.keys(result.per_family ?? {}).length} families.`);
+    }
+    // pln#568 slice 3 — registry cutover: backfill the registry/coordination
+    // families and emit the `registry_genesis` marker so the observer can trust
+    // the journal as authoritative for claims/assignments/runs/actions (drop the
+    // board_summary MCP seed). Incremental + idempotent; safe to re-run to upgrade
+    // a store that was journal-enabled before this slice landed.
+    const registry = runRegistryGenesisSupplement({ cwd });
+    if (registry.status === 'already_present') {
+        console.log(`✔ Registry cutover marker already present — observer authority unchanged.`);
+    }
+    else {
+        console.log(`✔ Registry cutover: ${registry.backfilled} registry entit(y/ies) backfilled, observer can now trust the journal for coordination counts (pln#568).`);
     }
 }
 function promoteMachineItems(cwd, dryRun) {
@@ -49,27 +97,43 @@ function promoteMachineItems(cwd, dryRun) {
         console.error('Error: cannot resolve user store. Run `brainclaw setup` first.');
         process.exit(1);
     }
-    const userState = loadState(userCwd);
-    // Move constraints
+    const movedIds = {
+        constraints: new Set(machineConstraints.map((c) => c.id)),
+        decisions: new Set(machineDecisions.map((d) => d.id)),
+        traps: new Set(machineTraps.map((t) => t.id)),
+    };
+    // Write target FIRST (a crash here leaves a duplicate, never silent loss),
+    // each side as an atomic locked RMW so concurrent writes are not clobbered.
+    mutateState((userState) => {
+        for (const c of machineConstraints) {
+            if (!userState.active_constraints.some((x) => x.id === c.id))
+                userState.active_constraints.push(c);
+        }
+        for (const d of machineDecisions) {
+            if (!userState.recent_decisions.some((x) => x.id === d.id))
+                userState.recent_decisions.push(d);
+        }
+        for (const t of machineTraps) {
+            if (!userState.known_traps.some((x) => x.id === t.id))
+                userState.known_traps.push(t);
+        }
+    }, userCwd);
+    // Then delete from source — mutateState persists with deleteMissing so the
+    // promoted entity files are actually unlinked from the project store.
+    mutateState((sourceState) => {
+        sourceState.active_constraints = sourceState.active_constraints.filter((x) => !movedIds.constraints.has(x.id));
+        sourceState.recent_decisions = sourceState.recent_decisions.filter((x) => !movedIds.decisions.has(x.id));
+        sourceState.known_traps = sourceState.known_traps.filter((x) => !movedIds.traps.has(x.id));
+    }, cwd);
     for (const c of machineConstraints) {
-        userState.active_constraints.push(c);
-        state.active_constraints = state.active_constraints.filter((x) => x.id !== c.id);
         appendAuditEntry({ actor: agent, action: 'update', item_id: c.id, item_type: 'constraint', reason: 'promote to user store (machine scope)' }, cwd);
     }
-    // Move decisions
     for (const d of machineDecisions) {
-        userState.recent_decisions.push(d);
-        state.recent_decisions = state.recent_decisions.filter((x) => x.id !== d.id);
         appendAuditEntry({ actor: agent, action: 'update', item_id: d.id, item_type: 'decision', reason: 'promote to user store (machine scope)' }, cwd);
     }
-    // Move traps
     for (const t of machineTraps) {
-        userState.known_traps.push(t);
-        state.known_traps = state.known_traps.filter((x) => x.id !== t.id);
         appendAuditEntry({ actor: agent, action: 'update', item_id: t.id, item_type: 'trap', reason: 'promote to user store (machine scope)' }, cwd);
     }
-    persistState(userState, userCwd);
-    persistState(state, cwd);
     console.log(`\n✔ Promoted ${total} item(s) to user store (${userCwd})`);
 }
 //# sourceMappingURL=migrate.js.map

package/dist/commands/prune.js

@@ -1,9 +1,11 @@
-import { loadState, saveState } from '../core/state.js';
-import { memoryExists } from '../core/io.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadState, persistState } from '../core/state.js';
+import { memoryExists, resolveEntityDir } from '../core/io.js';
 import { mutate } from '../core/mutation-pipeline.js';
 import { rebuildProjectMd } from '../core/markdown.js';
 import { deleteRuntimeNote, listRuntimeNotes } from '../core/runtime.js';
-import { expireStaleActiveClaims } from '../core/claims.js';
+import { expireStaleActiveClaims, isClaimExpired, listClaims } from '../core/claims.js';
 import { archiveStalePlansAndHandoffs } from '../core/archival.js';
 import { rotateAuditLogIfNeeded } from '../core/audit.js';
 import { analyzeMemory, analyzeAndApply, formatReport } from '../core/memory-compactor.js';
@@ -35,6 +37,10 @@ export function runPrune(options = {}) {
     }
     // Original prune logic
     const now = new Date().toISOString();
+    if (options.dryRun) {
+        previewPrune(cwd, now, options);
+        return;
+    }
     let prunedCount = 0;
     let expiredClaimsCount = 0;
     let expiredNotesCount = 0;
@@ -48,7 +54,9 @@ export function runPrune(options = {}) {
         }
         state.active_constraints = state.active_constraints.filter(c => c.status !== 'expired');
         prunedCount = originalLength - state.active_constraints.length;
-        saveState(state, cwd);
+        // deleteMissing: this RMW is atomic (loadState above runs under the same
+        // mutate() lock), so removing pruned files here cannot clobber concurrent writes.
+        persistState(state, cwd, { writeProjectMarkdown: false, deleteMissing: true });
         expiredClaimsCount = expireStaleActiveClaims(cwd);
         if (options.expired) {
             const notes = listRuntimeNotes(undefined, cwd);
@@ -83,4 +91,70 @@ export function runPrune(options = {}) {
         console.log(`✔ Pruned ${prunedCount} expired constraints, ${expiredClaimsCount} expired claims${archiveMsg}${rotateMsg}.`);
     }
 }
+function previewPrune(cwd, now, options) {
+    const state = loadState(cwd);
+    const expiredConstraints = state.active_constraints.filter((c) => c.status === 'expired' || (c.status === 'active' && c.expires_at && c.expires_at < now));
+    const expiredClaims = listClaims(cwd).filter((claim) => claim.status === 'active' && isClaimExpired(claim));
+    const expiredNotes = options.expired
+        ? listRuntimeNotes(undefined, cwd).filter((note) => note.expires_at && note.expires_at < now)
+        : [];
+    const archivePreview = options.archive ? previewArchive(cwd) : [];
+    console.log('Dry run: no files will be changed.');
+    console.log(`Would prune ${expiredConstraints.length} expired constraints.`);
+    for (const constraint of expiredConstraints) {
+        console.log(`  - constraint ${constraint.id}: ${constraint.text.slice(0, 80)}`);
+    }
+    console.log(`Would release ${expiredClaims.length} expired claims.`);
+    for (const claim of expiredClaims) {
+        console.log(`  - claim ${claim.id}: ${claim.scope}`);
+    }
+    if (options.expired) {
+        console.log(`Would delete ${expiredNotes.length} expired runtime notes.`);
+        for (const note of expiredNotes) {
+            console.log(`  - runtime note ${note.id}: ${note.agent}`);
+        }
+    }
+    if (options.archive) {
+        const total = archivePreview.reduce((sum, item) => sum + item.ids.length, 0);
+        console.log(`Would archive ${total} stale plans/handoffs.`);
+        for (const item of archivePreview) {
+            for (const id of item.ids) {
+                console.log(`  - ${item.entity} ${id}`);
+            }
+        }
+    }
+}
+function previewArchive(cwd) {
+    const maxAgeMs = 30 * 24 * 60 * 60 * 1000;
+    const cutoff = new Date(Date.now() - maxAgeMs).toISOString();
+    return [
+        {
+            entity: 'plans',
+            ids: listArchiveEligibleIds(cwd, 'plans', cutoff, (item) => item.status === 'done' || item.status === 'dropped'),
+        },
+        {
+            entity: 'handoffs',
+            ids: listArchiveEligibleIds(cwd, 'handoffs', cutoff, (item) => item.status === 'closed'),
+        },
+    ].filter((entry) => entry.ids.length > 0);
+}
+function listArchiveEligibleIds(cwd, entity, cutoffDate, isEligible) {
+    const dir = resolveEntityDir(entity, cwd, 'read');
+    if (!fs.existsSync(dir))
+        return [];
+    const ids = [];
+    for (const file of fs.readdirSync(dir).filter((entry) => entry.endsWith('.json') && entry !== 'archive.json')) {
+        try {
+            const item = JSON.parse(fs.readFileSync(path.join(dir, file), 'utf-8'));
+            const date = (item.completed_at ?? item.updated_at ?? item.created_at);
+            if (!isEligible(item))
+                continue;
+            if (date && date > cutoffDate)
+                continue;
+            ids.push(typeof item.id === 'string' ? item.id : path.basename(file, '.json'));
+        }
+        catch { /* ignore malformed files in preview */ }
+    }
+    return ids;
+}
 //# sourceMappingURL=prune.js.map

package/dist/commands/reflect.js

@@ -54,31 +54,37 @@ function runReflectBatchFromFile(filepath, baseOptions) {
             : [parsed];
     let created = 0;
     for (const rawEvent of rawEvents) {
+        // Only event-shape parse errors are skippable here. Errors raised by
+        // createCandidateFromInput (identity resolution, strict security blocks)
+        // MUST propagate: swallowing them silently dropped sensitive content and
+        // exited 0, defeating strict-import enforcement (pln#572).
+        let event;
         try {
-            const event = RuntimeEventSchema.parse(rawEvent);
-            if (!isReflectableRuntimeEvent(event)) {
-                continue;
-            }
-            const candidateType = event.candidate_type ?? mapEventTypeToCandidateType(event.event_type);
-            createCandidateFromInput(event.text, candidateType, {
-                ...baseOptions,
-                type: candidateType,
-                tag: event.tags.length ? event.tags : baseOptions.tag,
-                authorId: baseOptions.authorId ?? event.agent_id,
-                projectId: baseOptions.projectId ?? event.project_id,
-                hostId: baseOptions.hostId ?? event.host_id,
-                sessionId: baseOptions.sessionId ?? event.session_id,
-                source: baseOptions.source ?? event.agent,
-                severity: baseOptions.severity ?? event.severity,
-                from: baseOptions.from ?? event.from,
-                to: baseOptions.to ?? event.to,
-                path: baseOptions.path ?? event.related_paths?.[0],
-            }, false, true, true);
-            created++;
+            event = RuntimeEventSchema.parse(rawEvent);
         }
         catch {
             // skip malformed event records
+            continue;
+        }
+        if (!isReflectableRuntimeEvent(event)) {
+            continue;
         }
+        const candidateType = event.candidate_type ?? mapEventTypeToCandidateType(event.event_type);
+        createCandidateFromInput(event.text, candidateType, {
+            ...baseOptions,
+            type: candidateType,
+            tag: event.tags.length ? event.tags : baseOptions.tag,
+            authorId: baseOptions.authorId ?? event.agent_id,
+            projectId: baseOptions.projectId ?? event.project_id,
+            hostId: baseOptions.hostId ?? event.host_id,
+            sessionId: baseOptions.sessionId ?? event.session_id,
+            source: baseOptions.source ?? event.agent,
+            severity: baseOptions.severity ?? event.severity,
+            from: baseOptions.from ?? event.from,
+            to: baseOptions.to ?? event.to,
+            path: baseOptions.path ?? event.related_paths?.[0],
+        }, false, true, true);
+        created++;
     }
     console.log(`✔ Created ${created} candidate(s) from batch file`);
 }

package/dist/commands/register-agent.js

@@ -1,4 +1,4 @@
-import { registerAgentIdentity, setCurrentAgentIdentity } from '../core/agent-registry.js';
+import { listDebrisAgentIdentities, registerAgentIdentity, removeAgentIdentity, setCurrentAgentIdentity, } from '../core/agent-registry.js';
 import { memoryExists } from '../core/io.js';
 export function runRegisterAgent(agentName, options = {}) {
     if (!memoryExists()) {
@@ -26,4 +26,60 @@ export function runRegisterAgent(agentName, options = {}) {
     const fingerprintLabel = agent.identity_key ? `, fp=${agent.identity_key.fingerprint.slice(0, 12)}` : '';
     console.log(`✔ Agent registered: ${agent.agent_name} (${agent.agent_id}, kind=${agent.kind}${capabilitiesLabel}${fingerprintLabel})${currentLabel}`);
 }
+/**
+ * Guarded identity removal (pln#562 step 2). Without --force, only known
+ * debris identities (test fixtures, alias leftovers) can be removed.
+ */
+export function runRemoveAgent(agentNameOrId, options = {}) {
+    if (!memoryExists()) {
+        console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
+        process.exit(1);
+    }
+    try {
+        const removed = removeAgentIdentity(agentNameOrId, { force: options.force });
+        if (options.json) {
+            console.log(JSON.stringify({ removed: true, agent: removed }, null, 2));
+            return;
+        }
+        console.log(`✔ Agent identity removed: ${removed.agent_name} (${removed.agent_id})`);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (options.json) {
+            console.log(JSON.stringify({ removed: false, error: message }, null, 2));
+        }
+        else {
+            console.error(`✖ ${message}`);
+        }
+        process.exitCode = 1;
+    }
+}
+/** List identities flagged as registration debris, without removing anything. */
+export function runListDebrisAgents(options = {}) {
+    if (!memoryExists()) {
+        console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
+        process.exit(1);
+    }
+    const debris = listDebrisAgentIdentities();
+    if (options.json) {
+        console.log(JSON.stringify({
+            debris: debris.map((d) => ({
+                agent_id: d.identity.agent_id,
+                agent_name: d.identity.agent_name,
+                trust_level: d.identity.trust_level,
+                reason: d.reason,
+            })),
+        }, null, 2));
+        return;
+    }
+    if (debris.length === 0) {
+        console.log('✔ No debris agent identities found.');
+        return;
+    }
+    console.log(`⚠ ${debris.length} debris agent identit${debris.length === 1 ? 'y' : 'ies'} found:`);
+    for (const d of debris) {
+        console.log(`  - ${d.identity.agent_name} (${d.identity.agent_id}): ${d.reason}`);
+    }
+    console.log('Remove with `brainclaw register-agent <name> --remove`.');
+}
 //# sourceMappingURL=register-agent.js.map

package/dist/commands/repair.js

@@ -26,6 +26,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { memoryExists, memoryDir } from '../core/io.js';
+import { migrateRuntimeNoteIdPrefixes } from '../core/runtime.js';
 import { runDoctor } from './doctor.js';
 /**
  * Execute a single repair candidate. Returns the outcome; never throws.
@@ -66,6 +67,25 @@ function executeCandidate(candidate, cwd) {
                 fs.renameSync(sourceAbs, destAbs);
                 return { action: candidate.action, target: candidate.target, status: 'applied' };
             }
+            case 'migrate_runtime_note_ids': {
+                // can_b8d53d18 — lossless rename of legacy run_-prefixed runtime note
+                // ids to rtn_ (file rename + id rewrite, no deletion of note content).
+                const migration = migrateRuntimeNoteIdPrefixes(cwd);
+                if (migration.errors.length > 0) {
+                    return {
+                        action: candidate.action,
+                        target: candidate.target,
+                        status: migration.migrated.length > 0 ? 'applied' : 'failed',
+                        reason: `migrated ${migration.migrated.length}, errors: ${migration.errors.join('; ')}`,
+                    };
+                }
+                return {
+                    action: candidate.action,
+                    target: candidate.target,
+                    status: 'applied',
+                    reason: `migrated ${migration.migrated.length} runtime note id(s) to rtn_`,
+                };
+            }
             case 'quarantine_inbox_message': {
                 // Unsafe: move malformed message to a quarantine directory so a human
                 // can inspect it. Never deletes. Requires includeUnsafe.

package/dist/commands/session-end.js

@@ -36,13 +36,15 @@ import { appendAuditEntry, readAuditLog } from '../core/audit.js';
 import { requireMinimumTrustLevel, requireRegisteredAgentIdentity } from '../core/agent-registry.js';
 import { loadSessionSnapshot } from '../commands/session-start.js';
 import { extractFilesFromDiff } from '../commands/handoff.js';
+import { capHandoffDiff } from '../core/handoff-snapshot.js';
 import { suggestCompaction } from '../core/memory-compactor.js';
 import { dispatchReview } from '../core/dispatcher.js';
 export const REFLECTION_QUESTIONS = [
-    'What was the biggest time waste in this session, and how could it have been avoided?',
-    'What should have been done differently (design, process, or approach)?',
-    'What should brainclaw itself improve based on this session?',
+    'Dogfooding the project — using brainclaw to do real work this session, what friction did you hit (slow reads, confusing surfaces, missing affordances, awkward workflows)? What concrete change to the project would have removed it?',
+    'Your surfaces, skills & tools — did your generated surface files (CLAUDE.md / agent surface), skills (SKILL.md), or tools (MCP / CLI) help or get in the way? Name at least one concrete edit that would make them serve you better next time.',
+    'What was the biggest time waste this session, and how could it have been avoided?',
 ];
+export const REFLECTION_INSTRUCTION = 'Take a short reflection pass before you stop. For each question, capture anything ACTIONABLE as durable memory with bclaw_quick_capture (type "trap" for a sharp edge to avoid, "decision"/"note" for an improvement idea) so it enters the improvement backlog — improvements to the project AND to your own brainclaw surfaces/skills/tools both count. Use bclaw_write_note with tags ["reflection", "session:<id>"] for free-form narrative. Skipping is fine if the session was trivial.';
 export async function runSessionEnd(options = {}) {
     try {
         const result = await endSession(options);
@@ -362,10 +364,14 @@ export async function endSession(options = {}) {
         compaction_hint: compactionHint,
         ...(reflectedHandoff ? { handoff: reflectedHandoff } : {}),
     };
-    if (options.reflect) {
+    // pln#564 — session_end pushes the agent into a short dogfooding reflection
+    // by DEFAULT (opt-out via reflect:false). The session_end runtime note is the
+    // natural trigger to ask "did the tooling serve me, and what should improve?"
+    // — both for the project worked on and for the agent's own brainclaw surfaces.
+    if (options.reflect !== false) {
         result.reflection_prompt = {
             questions: [...REFLECTION_QUESTIONS],
-            instruction: `Please reflect on this session and answer each question. Write your answers using bclaw_write_note with tags ["reflection", "session:${sessionId}"]. One note per question, or a single combined note.`,
+            instruction: REFLECTION_INSTRUCTION.replace('session:<id>', `session:${sessionId}`),
         };
     }
     return result;
@@ -395,7 +401,10 @@ function materializeSessionHandoff(input) {
                 linked_plans: input.linkedPlans.length > 0 ? input.linkedPlans : undefined,
             }
             : undefined,
-        snapshot: input.fullDiff ? { diff: input.fullDiff } : undefined,
+        // pln#569 — cap the inline diff to a preview + digest (the full ~450 KB
+        // uncommitted diff bloated auto-handoffs to 53 MB of the journal; no consumer
+        // reads past a bounded prefix and the worktree branch carries the full diff).
+        snapshot: capHandoffDiff(input.fullDiff),
     });
     persistState(state, cwd);
     return { handoff_id: id, plan_id: input.planId };

package/dist/commands/session-start.js

@@ -15,7 +15,8 @@ import { releaseStaleClaimsFromOtherAgents } from '../core/claims.js';
 import { SessionSnapshotSchema } from '../core/schema.js';
 import { auditLocalAgentWorkspaceFiles } from '../core/agent-files.js';
 import { buildAgentInventory, loadAgentInventory, saveAgentInventory, diffInventory } from '../core/agent-inventory.js';
-import { checkMemoryPressure } from '../core/gc-semantic.js';
+import { checkMemoryPressure, enforceRuntimeNoteRetention } from '../core/gc-semantic.js';
+import { maybeCreateCheckpoint } from '../core/events/checkpoint.js';
 import { pullSignalsFromLinkedProjects, markSignalProcessed } from '../core/federation-transport.js';
 import { pullSignalsFromCloud, isCloudSyncEnabled } from '../core/federation-cloud.js';
 import { materializeFederationSignal } from '../core/federation-materialize.js';
@@ -191,6 +192,22 @@ export async function startSession(options = {}) {
                 inventoryAdvisory = lines;
         }
         catch { /* non-fatal — inventory scan failure should not block session start */ }
+        // pln#564 step B — cap the runtime-note tree on session start (no LLM gate,
+        // unlike the compaction-phase archiveSessionNotes). Keeps the newest N
+        // session/lifecycle notes per agent + all genuine observations, parks the
+        // rest. Bounds the buildContext read-path scan (trp_439fec51). Best-effort.
+        try {
+            enforceRuntimeNoteRetention({ cwd: options.cwd });
+        }
+        catch { /* non-fatal — retention sweep must never block session start */ }
+        // pln#566 Inc0 — keep a recent journal-derived checkpoint available off the
+        // hot path so the (capability-gated, OFF by default) checkpointRead read
+        // path has something to serve once enabled. Gated by a growth threshold so
+        // it only builds occasionally; journal-derived (F6). Best-effort.
+        try {
+            maybeCreateCheckpoint(options.cwd);
+        }
+        catch { /* non-fatal — checkpoint build must never block session start */ }
     }
     // Shared checkout detection: warn if other active sessions share the same worktree
     let sharedCheckoutWarning;

package/dist/commands/setup-security.js

@@ -2,7 +2,14 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { memoryExists, memoryPath, ensureMemoryDir } from '../core/io.js';
 import { loadConfig, saveConfig } from '../core/config.js';
-import { generateBashGuard, generatePowerShellGuard, generatePipBashGuard } from '../core/security-guard.js';
+import { generateBashGuard, generatePowerShellGuard, generatePipBashGuard, } from '../core/security-guard.js';
+/**
+ * Each guard wraps a single install command. The CLI invocation that gets
+ * called is identical — only ORIGINAL_CMD differs — so we generate one
+ * script per supported tool with the right ORIGINAL_CMD baked in.
+ */
+const NPM_LIKE = ['npm', 'pnpm', 'yarn'];
+const PIP_LIKE = ['pip', 'pip3'];
 export function runSetupSecurity(options = {}) {
     const cwd = options.cwd;
     if (!memoryExists(cwd)) {
@@ -13,7 +20,16 @@ export function runSetupSecurity(options = {}) {
     const mode = options.mode ?? 'advisory';
     // Enable preinstall in config
     if (!config.security) {
-        config.security = { mode: 'warn', strict_redaction: false, block_sensitive_paths: true };
+        config.security = {
+            mode: 'warn',
+            strict_redaction: false,
+            block_sensitive_paths: true,
+            token_detection: {
+                enabled: true,
+                entropy: { enabled: true, min_length: 32, min_entropy: 4.0 },
+                detectors: {},
+            },
+        };
     }
     config.security.preinstall = {
         enabled: true,
@@ -46,25 +62,30 @@ export function runSetupSecurity(options = {}) {
     if (!fs.existsSync(guardDir)) {
         fs.mkdirSync(guardDir, { recursive: true });
     }
-    // npm guard (bash)
-    const npmBashPath = path.join(guardDir, 'npm');
-    fs.writeFileSync(npmBashPath, generateBashGuard(brainclawBin), { mode: 0o755 });
-    // npm guard (PowerShell)
-    const npmPs1Path = path.join(guardDir, 'npm.ps1');
-    fs.writeFileSync(npmPs1Path, generatePowerShellGuard(brainclawBin));
-    // pip guard (bash)
-    const pipBashPath = path.join(guardDir, 'pip');
-    fs.writeFileSync(pipBashPath, generatePipBashGuard(brainclawBin), { mode: 0o755 });
-    // pip guard (PowerShell)
-    const pipPs1Path = path.join(guardDir, 'pip.ps1');
-    fs.writeFileSync(pipPs1Path, generatePowerShellGuard(brainclawBin).replace('} else { "npm" }', '} else { "pip" }'));
+    const writtenScripts = [];
+    for (const cmd of NPM_LIKE) {
+        const bashPath = path.join(guardDir, cmd);
+        const bashScript = generateBashGuard(brainclawBin).replace('ORIGINAL_CMD="${BRAINCLAW_GUARD_ORIGINAL_CMD:-npm}"', `ORIGINAL_CMD="\${BRAINCLAW_GUARD_ORIGINAL_CMD:-${cmd}}"`);
+        fs.writeFileSync(bashPath, bashScript, { mode: 0o755 });
+        writtenScripts.push(bashPath);
+        const ps1Path = path.join(guardDir, `${cmd}.ps1`);
+        const ps1Script = generatePowerShellGuard(brainclawBin).replace('} else { "npm" }', `} else { "${cmd}" }`);
+        fs.writeFileSync(ps1Path, ps1Script);
+        writtenScripts.push(ps1Path);
+    }
+    for (const cmd of PIP_LIKE) {
+        const bashPath = path.join(guardDir, cmd);
+        fs.writeFileSync(bashPath, generatePipBashGuard(brainclawBin).replace('ORIGINAL_CMD="${BRAINCLAW_GUARD_ORIGINAL_CMD:-pip}"', `ORIGINAL_CMD="\${BRAINCLAW_GUARD_ORIGINAL_CMD:-${cmd}}"`), { mode: 0o755 });
+        writtenScripts.push(bashPath);
+        const ps1Path = path.join(guardDir, `${cmd}.ps1`);
+        fs.writeFileSync(ps1Path, generatePowerShellGuard(brainclawBin).replace('} else { "npm" }', `} else { "${cmd}" }`));
+        writtenScripts.push(ps1Path);
+    }
     console.log(`\u2705 Security gate enabled (mode: ${mode})`);
     console.log('');
     console.log('Generated wrapper scripts:');
-    console.log(`  ${npmBashPath}`);
-    console.log(`  ${npmPs1Path}`);
-    console.log(`  ${pipBashPath}`);
-    console.log(`  ${pipPs1Path}`);
+    for (const p of writtenScripts)
+        console.log(`  ${p}`);
     console.log('');
     console.log('To activate, prepend the guard directory to your PATH:');
     console.log(`  export PATH="${guardDir}:$PATH"    # bash/zsh`);