fluffy-context 0.6.0 → 0.7.2

package/dist/src/cognition/journal.js

@@ -5,6 +5,15 @@ import { resolveProjectRoot } from '../project/project-resolver.js';
 import { loadManifest } from '../runtime/init.js';
 import { withLock } from '../storage/lock.js';
 import { cognitionJournalDirectory, locksDirectory } from '../storage/layout.js';
+const eventTypes = new Set([
+    'runtime.enabled', 'runtime.started', 'runtime.stopped', 'host.session.started', 'host.prompt.submitted',
+    'git.state.observed', 'git.branch.changed', 'git.head.changed', 'workspace.paths.changed',
+    'context.checkpoint.imported', 'context.state.recorded', 'note.recorded', 'note.resolved', 'note.absorbed',
+    'knowledge.proposed', 'knowledge.verified', 'knowledge.deprecated', 'knowledge.rejected',
+    'deadend.proposed', 'deadend.verified', 'deadend.obsoleted', 'deadend.rejected', 'record.used',
+    'projection.advanced', 'projection.failed',
+]);
+const sourceKinds = new Set(['cli', 'claude-hook', 'mcp', 'git-observer', 'fs-observer', 'migration']);
 const segmentName = '00000001.ndjson';
 function canonical(value) {
     if (value === null || typeof value !== 'object')
@@ -33,6 +42,49 @@ async function journalFiles(projectRoot) {
         throw error;
     }
 }
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function validGitAnchor(value) {
+    return isRecord(value)
+        && (typeof value.worktreeId === 'string' || value.worktreeId === null)
+        && (typeof value.branch === 'string' || value.branch === null)
+        && (typeof value.ref === 'string' || value.ref === null)
+        && (typeof value.head === 'string' || value.head === null);
+}
+function validIsoDate(value) {
+    return typeof value === 'string' && Number.isFinite(Date.parse(value));
+}
+function validateEventShape(event, projectId, file, line) {
+    if (!isRecord(event)
+        || event.schemaVersion !== 2
+        || typeof event.eventId !== 'string'
+        || event.eventId.length === 0
+        || typeof event.type !== 'string'
+        || !eventTypes.has(event.type)
+        || !validIsoDate(event.occurredAt)
+        || !validIsoDate(event.observedAt)
+        || event.projectId !== projectId
+        || !isRecord(event.source)
+        || typeof event.source.kind !== 'string'
+        || !sourceKinds.has(event.source.kind)
+        || (event.source.instanceId !== undefined && typeof event.source.instanceId !== 'string')
+        || (event.correlationId !== undefined && typeof event.correlationId !== 'string')
+        || typeof event.idempotencyKey !== 'string'
+        || event.idempotencyKey.length === 0
+        || !validGitAnchor(event.git)
+        || !isRecord(event.privacy)
+        || (event.privacy.classification !== 'metadata' && event.privacy.classification !== 'redacted-text')
+        || typeof event.privacy.redactionCount !== 'number'
+        || !Number.isSafeInteger(event.privacy.redactionCount)
+        || event.privacy.redactionCount < 0
+        || !isRecord(event.payload)
+        || (event.previousHash !== null && typeof event.previousHash !== 'string')
+        || typeof event.hash !== 'string'
+        || event.hash.length === 0) {
+        throw new Error(`invalid journal record schema at ${file}:${line}`);
+    }
+}
 async function recoverPartialTail(projectRoot) {
     const files = await journalFiles(projectRoot);
     const file = files.at(-1);
@@ -46,13 +98,15 @@ async function recoverPartialTail(projectRoot) {
     const tail = content.slice(boundary + 1);
     try {
         JSON.parse(tail);
+        await appendFile(filePath, '\n', 'utf8');
     }
     catch {
         await truncate(filePath, boundary < 0 ? 0 : boundary + 1);
     }
 }
-export async function readJournal(startPath) {
+export async function readJournal(startPath, options = {}) {
     const projectRoot = await resolveProjectRoot(startPath);
+    const projectId = (await loadManifest(projectRoot)).projectId;
     const events = [];
     let previousHash = null;
     for (const file of await journalFiles(projectRoot)) {
@@ -67,12 +121,13 @@ export async function readJournal(startPath) {
                 event = JSON.parse(line);
             }
             catch (error) {
-                if (index === lines.length - 1 && !content.endsWith('\n'))
+                if (options.allowPartialTail !== false && index === lines.length - 1 && !content.endsWith('\n'))
                     break;
                 throw new Error(`invalid journal record ${file}:${index + 1}: ${error instanceof Error ? error.message : 'invalid JSON'}`);
             }
+            validateEventShape(event, projectId, file, index + 1);
             const { hash, ...withoutHash } = event;
-            if (event.schemaVersion !== 2 || !event.eventId || event.previousHash !== previousHash || hash !== eventHash(withoutHash)) {
+            if (event.previousHash !== previousHash || hash !== eventHash(withoutHash)) {
                 throw new Error(`invalid journal hash chain at ${file}:${index + 1}`);
             }
             previousHash = event.hash;
@@ -81,14 +136,38 @@ export async function readJournal(startPath) {
     }
     return events;
 }
+export async function verifyJournal(startPath) {
+    return readJournal(startPath, { allowPartialTail: false });
+}
 export async function appendEvent(startPath, input) {
     const projectRoot = await resolveProjectRoot(startPath);
     return withLock(`${locksDirectory(projectRoot)}/cognition-journal.lock`, async () => {
         await recoverPartialTail(projectRoot);
         const existing = await readJournal(projectRoot);
         const duplicate = existing.find((event) => event.idempotencyKey === input.idempotencyKey);
-        if (duplicate)
+        if (duplicate) {
+            const candidate = {
+                type: input.type,
+                source: input.source ?? { kind: 'cli' },
+                correlationId: input.correlationId,
+                idempotencyKey: input.idempotencyKey,
+                git: input.git ?? { worktreeId: null, branch: null, ref: null, head: null },
+                privacy: input.privacy ?? { classification: 'metadata', redactionCount: 0 },
+                payload: input.payload,
+            };
+            const existingSemantic = {
+                type: duplicate.type,
+                source: duplicate.source,
+                correlationId: duplicate.correlationId,
+                idempotencyKey: duplicate.idempotencyKey,
+                git: duplicate.git,
+                privacy: duplicate.privacy,
+                payload: duplicate.payload,
+            };
+            if (canonical(candidate) !== canonical(existingSemantic))
+                throw new Error(`idempotency key conflict: ${input.idempotencyKey}`);
             return { event: duplicate, appended: false };
+        }
         const now = new Date().toISOString();
         const eventWithoutHash = {
             eventId: input.eventId ?? eventId(),

package/dist/src/cognition/migration-v1.js

@@ -105,7 +105,7 @@ async function sourceRecords(projectRoot) {
 async function writeV2Metadata(projectRoot) {
     const v1 = await loadManifest(projectRoot);
     const manifest = { schemaVersion: 2, layoutVersion: COGNITION_LAYOUT_VERSION, projectId: v1.projectId, createdAt: new Date().toISOString(), policyVersion: 1 };
-    const policy = { schemaVersion: 2, enabled: false, allowHookStartup: false, inactivityTimeoutMs: 300_000, promptIntentMaxChars: 500, filesystemEventsEnabled: false, retentionMaxBytes: 64 * 1024 * 1024 };
+    const policy = { schemaVersion: 2, enabled: true, autoStart: true, allowHookStartup: true, inactivityTimeoutMs: 300_000, promptIntentMaxChars: 500, filesystemEventsEnabled: false, retentionMaxBytes: 64 * 1024 * 1024 };
     await Promise.all([atomicWriteJson(cognitionManifestPath(projectRoot), manifest), atomicWriteJson(cognitionPolicyPath(projectRoot), policy)]);
 }
 async function quarantineReadiness(projectRoot, readiness) {

package/dist/src/cognition/orient.js

@@ -1,11 +1,12 @@
 import { access } from 'node:fs/promises';
 import { readGitWorktreeState } from '../git/git-adapter.js';
-import { cognitionManifestPath, cognitionPolicyPath } from '../storage/layout.js';
+import { cognitionManifestPath } from '../storage/layout.js';
 import { readJson } from '../storage/json-store.js';
 import { loadManifest } from '../runtime/init.js';
 import { readJournal } from './journal.js';
 import { projectEvents, workspaceKey } from './projections.js';
 import { buildRetrievalProjection } from './retrieval.js';
+import { loadRuntimePolicy } from './policy.js';
 import { v1Synced } from './v1-bridge.js';
 function contextReference(value) {
     const boundary = value.lastIndexOf(':');
@@ -48,7 +49,7 @@ export async function selectV2Orientation(projectRoot, contextId) {
         const [manifest, cognition, policy] = await Promise.all([
             loadManifest(projectRoot),
             readJson(cognitionManifestPath(projectRoot)),
-            readJson(cognitionPolicyPath(projectRoot)),
+            loadRuntimePolicy(projectRoot),
         ]);
         if (cognition.schemaVersion !== 2 || cognition.projectId !== manifest.projectId || !policy.enabled || !await v1Synced(projectRoot))
             return null;
@@ -86,7 +87,7 @@ export async function selectV2Orientation(projectRoot, contextId) {
 export async function v2Enabled(projectRoot) {
     try {
         await access(cognitionManifestPath(projectRoot));
-        return (await readJson(cognitionPolicyPath(projectRoot))).enabled;
+        return (await loadRuntimePolicy(projectRoot)).enabled;
     }
     catch {
         return false;

package/dist/src/cognition/policy.d.ts

@@ -0,0 +1,4 @@
+import type { CognitionRuntimePolicy } from './types.js';
+export declare function normalizeRuntimePolicy(value: Partial<CognitionRuntimePolicy>): CognitionRuntimePolicy;
+export declare function loadRuntimePolicy(projectRoot: string): Promise<CognitionRuntimePolicy>;
+export declare function writeRuntimePolicy(projectRoot: string, policy: CognitionRuntimePolicy): Promise<void>;

package/dist/src/cognition/policy.js

@@ -0,0 +1,49 @@
+import { atomicWriteJson } from '../storage/atomic-write.js';
+import { cognitionPolicyPath } from '../storage/layout.js';
+import { readJson } from '../storage/json-store.js';
+const defaults = {
+    schemaVersion: 2,
+    enabled: true,
+    autoStart: true,
+    allowHookStartup: true,
+    inactivityTimeoutMs: 300_000,
+    promptIntentMaxChars: 500,
+    filesystemEventsEnabled: false,
+    retentionMaxBytes: 64 * 1024 * 1024,
+};
+function booleanValue(value, fallback, field) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'boolean')
+        throw new Error(`runtime policy field ${field} must be boolean`);
+    return value;
+}
+function nonNegativeInteger(value, fallback, field) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0)
+        throw new Error(`runtime policy field ${field} must be a non-negative integer`);
+    return value;
+}
+export function normalizeRuntimePolicy(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('runtime policy must be an object');
+    if (value.schemaVersion !== undefined && value.schemaVersion !== 2)
+        throw new Error('unsupported runtime policy schema');
+    return {
+        ...defaults,
+        enabled: booleanValue(value.enabled, defaults.enabled, 'enabled'),
+        autoStart: booleanValue(value.autoStart, defaults.autoStart, 'autoStart'),
+        allowHookStartup: booleanValue(value.allowHookStartup, defaults.allowHookStartup, 'allowHookStartup'),
+        inactivityTimeoutMs: nonNegativeInteger(value.inactivityTimeoutMs, defaults.inactivityTimeoutMs, 'inactivityTimeoutMs'),
+        promptIntentMaxChars: nonNegativeInteger(value.promptIntentMaxChars, defaults.promptIntentMaxChars, 'promptIntentMaxChars'),
+        filesystemEventsEnabled: booleanValue(value.filesystemEventsEnabled, defaults.filesystemEventsEnabled, 'filesystemEventsEnabled'),
+        retentionMaxBytes: nonNegativeInteger(value.retentionMaxBytes, defaults.retentionMaxBytes, 'retentionMaxBytes'),
+    };
+}
+export async function loadRuntimePolicy(projectRoot) {
+    return normalizeRuntimePolicy(await readJson(cognitionPolicyPath(projectRoot)));
+}
+export async function writeRuntimePolicy(projectRoot, policy) {
+    await atomicWriteJson(cognitionPolicyPath(projectRoot), normalizeRuntimePolicy(policy));
+}

package/dist/src/cognition/runtime.d.ts

@@ -3,10 +3,29 @@ export interface RuntimeServer {
     lease: RuntimeLease;
     close(reason?: string): Promise<void>;
 }
-export declare function serveRuntime(startPath?: string): Promise<RuntimeServer>;
+interface RuntimeServeOptions {
+    inactivityTimeoutMs?: number;
+    heartbeatIntervalMs?: number;
+    pollIntervalMs?: number;
+}
+export interface EnsureRuntimeOptions {
+    source?: 'claude-hook' | 'mcp' | 'cli';
+    timeoutMs?: number;
+}
+export interface EnsureRuntimeResult {
+    projectRoot: string;
+    started: boolean;
+    running: boolean;
+    skipped: 'disabled' | 'not-migrated' | 'already-running' | 'startup-in-progress' | 'startup-failed' | 'unavailable' | null;
+}
+export declare function serveRuntime(startPath?: string, options?: RuntimeServeOptions): Promise<RuntimeServer>;
 export declare function runtimeStatus(startPath?: string): Promise<RuntimeStatus>;
 export declare function enableRuntime(startPath?: string): Promise<RuntimeStatus>;
 export declare function disableRuntime(startPath?: string): Promise<RuntimeStatus>;
+export declare function setFilesystemEvents(startPath: string | undefined, enabled: boolean): Promise<RuntimeStatus>;
 export declare function startRuntime(startPath?: string): Promise<RuntimeStatus>;
+export declare function ensureRuntimeForSession(startPath?: string, options?: EnsureRuntimeOptions): Promise<EnsureRuntimeResult>;
 export declare function stopRuntime(startPath?: string): Promise<RuntimeStatus>;
 export declare function observeRuntime(startPath?: string): Promise<boolean>;
+export declare function touchRuntime(startPath?: string): Promise<boolean>;
+export {};

package/dist/src/cognition/runtime.js

@@ -9,8 +9,11 @@ import { loadManifest } from '../runtime/init.js';
 import { atomicWriteJson } from '../storage/atomic-write.js';
 import { readJson } from '../storage/json-store.js';
 import { withLock } from '../storage/lock.js';
-import { cognitionManifestPath, cognitionPolicyPath, cognitionRuntimeLeasePath, cognitionRuntimeSecretPath, locksDirectory } from '../storage/layout.js';
+import { cognitionManifestPath, cognitionRuntimeLeasePath, cognitionRuntimeSecretPath, cognitionRuntimeStartupPath, locksDirectory } from '../storage/layout.js';
 import { appendEvent } from './journal.js';
+import { rebuildProjections } from './projections.js';
+import { loadRuntimePolicy, writeRuntimePolicy } from './policy.js';
+import { FilesystemObserver } from './filesystem-observer.js';
 import { GitObserver } from './git-observer.js';
 import { reconcileV1State } from './migration-v1.js';
 import { v1Synced } from './v1-bridge.js';
@@ -19,6 +22,8 @@ const protocolVersion = 1;
 const maxFrameBytes = 16 * 1024;
 const pollIntervalMs = 2_000;
 const cliPath = fileURLToPath(new URL('../cli/main.js', import.meta.url));
+const startupPromises = new Map();
+const startupMarkerTimeoutMs = 10_000;
 function createInstanceId() {
     return crypto.randomBytes(12).toString('hex');
 }
@@ -44,11 +49,21 @@ async function exists(filePath) {
     }
 }
 async function loadPolicy(projectRoot) {
-    return readJson(cognitionPolicyPath(projectRoot));
+    return loadRuntimePolicy(projectRoot);
 }
 async function loadLease(projectRoot) {
     return readJson(cognitionRuntimeLeasePath(projectRoot)).catch(() => null);
 }
+async function loadStartupMarker(projectRoot) {
+    return readJson(cognitionRuntimeStartupPath(projectRoot)).catch(() => null);
+}
+async function removeOwnedRuntimeFiles(projectRoot, instanceId) {
+    const current = await loadLease(projectRoot);
+    if (current?.instanceId !== instanceId)
+        return;
+    await rm(cognitionRuntimeLeasePath(projectRoot), { force: true });
+    await rm(cognitionRuntimeSecretPath(projectRoot), { force: true });
+}
 async function request(projectRoot, lease, method) {
     let secret;
     try {
@@ -92,23 +107,52 @@ async function liveLease(projectRoot, lease) {
 async function writeLease(projectRoot, lease) {
     await atomicWriteJson(cognitionRuntimeLeasePath(projectRoot), lease);
 }
-async function closeServer(projectRoot, server, observer, heartbeat, poller, inactivity, lease, reason) {
-    clearInterval(heartbeat);
-    clearInterval(poller);
-    clearTimeout(inactivity);
-    await observer.drain();
-    await new Promise((resolve) => server.close(() => resolve()));
-    await new Promise((resolve) => setImmediate(resolve));
-    await rm(cognitionRuntimeLeasePath(projectRoot), { force: true });
-    await rm(cognitionRuntimeSecretPath(projectRoot), { force: true });
-    await appendEvent(projectRoot, {
-        type: 'runtime.stopped',
-        source: { kind: 'cli', instanceId: lease.instanceId },
-        idempotencyKey: `runtime:stopped:${lease.instanceId}`,
-        payload: { reason },
-    });
+async function closeServer(projectRoot, server, observer, filesystem, heartbeat, poller, inactivity, background, leaseWrite, lease, reason) {
+    if (heartbeat)
+        clearInterval(heartbeat);
+    if (poller)
+        clearInterval(poller);
+    if (inactivity)
+        clearTimeout(inactivity);
+    let failure;
+    try {
+        filesystem.stop();
+        await filesystem.flush();
+        await observer.drain();
+        await filesystem.drain();
+        await background;
+        await rebuildProjections(projectRoot);
+        await leaseWrite;
+    }
+    catch (error) {
+        failure = error;
+    }
+    finally {
+        await new Promise((resolve) => {
+            if (!server.listening) {
+                resolve();
+                return;
+            }
+            server.close(() => resolve());
+        });
+        await new Promise((resolve) => setImmediate(resolve));
+        await removeOwnedRuntimeFiles(projectRoot, lease.instanceId);
+    }
+    try {
+        await appendEvent(projectRoot, {
+            type: 'runtime.stopped',
+            source: { kind: 'cli', instanceId: lease.instanceId },
+            idempotencyKey: `runtime:stopped:${lease.instanceId}`,
+            payload: { reason },
+        });
+    }
+    catch (error) {
+        failure ??= error;
+    }
+    if (failure)
+        throw failure;
 }
-function attachProtocol(projectRoot, server, observer, secret, lease, touch, close) {
+function attachProtocol(server, secret, lease, touch, observe, close) {
     server.on('connection', (socket) => {
         socket.setEncoding('utf8');
         let buffer = '';
@@ -142,7 +186,7 @@ function attachProtocol(projectRoot, server, observer, secret, lease, touch, clo
             }
             if (request.method === 'observe') {
                 try {
-                    const result = await observer.observeNow();
+                    const result = await observe();
                     socket.end(`${JSON.stringify({ ok: true, result: { changed: result.changed } })}\n`);
                 }
                 catch {
@@ -159,11 +203,14 @@ function attachProtocol(projectRoot, server, observer, secret, lease, touch, clo
         });
     });
 }
-export async function serveRuntime(startPath) {
+export async function serveRuntime(startPath, options = {}) {
     const projectRoot = await resolveProjectRoot(startPath);
     const currentPolicy = await loadPolicy(projectRoot);
     if (!currentPolicy.enabled)
         throw new Error('runtime is disabled; run ctx runtime enable first');
+    const inactivityTimeoutMs = options.inactivityTimeoutMs ?? currentPolicy.inactivityTimeoutMs;
+    const heartbeatIntervalMs = options.heartbeatIntervalMs ?? 5_000;
+    const runtimePollIntervalMs = options.pollIntervalMs ?? pollIntervalMs;
     const existing = await liveLease(projectRoot);
     if (existing)
         throw new Error('runtime is already running');
@@ -182,21 +229,55 @@ export async function serveRuntime(startPath) {
     const lease = { schemaVersion: 2, protocolVersion, projectId: manifest.projectId, instanceId: createInstanceId(), pid: process.pid, host, port: address.port, startedAt: now, heartbeatAt: now };
     const secret = createToken();
     const observer = new GitObserver(projectRoot);
-    let closed = false;
-    let heartbeat;
-    let poller;
-    let inactivity;
+    let filesystem;
+    let heartbeat = null;
+    let poller = null;
+    let inactivity = null;
+    let background = Promise.resolve();
+    let leaseWrite = Promise.resolve();
+    let filesystemEventPending = false;
+    let closing = null;
+    const enqueueObservation = (operation) => {
+        const next = background.then(operation, operation);
+        background = next.then(() => undefined, () => undefined);
+        return next;
+    };
     const close = async (reason) => {
-        if (closed)
-            return;
-        closed = true;
-        await closeServer(projectRoot, server, observer, heartbeat, poller, inactivity, lease, reason);
+        if (closing)
+            return closing;
+        closing = closeServer(projectRoot, server, observer, filesystem, heartbeat, poller, inactivity, background, leaseWrite, lease, reason);
+        return closing;
     };
     const touch = () => {
-        clearTimeout(inactivity);
-        inactivity = setTimeout(() => { void close('inactivity'); }, currentPolicy.inactivityTimeoutMs);
+        if (inactivity)
+            clearTimeout(inactivity);
+        inactivity = setTimeout(() => { void close('inactivity').catch(() => undefined); }, inactivityTimeoutMs);
     };
-    attachProtocol(projectRoot, server, observer, secret, lease, touch, close);
+    const observe = () => enqueueObservation(async () => {
+        const [gitResult, filesystemResult] = await Promise.all([
+            observer.observeNow(),
+            filesystem.observeNow(),
+        ]);
+        const synced = await v1Synced(projectRoot);
+        if (!synced)
+            await reconcileV1State(projectRoot);
+        if (gitResult.changed || filesystemResult.changed || filesystemEventPending || !synced) {
+            await rebuildProjections(projectRoot);
+            filesystemEventPending = false;
+        }
+        const changed = gitResult.changed || filesystemResult.changed || filesystemEventPending || !synced;
+        if (changed)
+            touch();
+        return { changed };
+    });
+    filesystem = new FilesystemObserver(projectRoot, {
+        anchor: () => ({ worktreeId: observer.current?.worktreeId ?? null, branch: observer.current?.branch ?? null, ref: observer.current?.ref ?? null, head: observer.current?.commit ?? null }),
+        onChanged: () => {
+            filesystemEventPending = true;
+            touch();
+        },
+    });
+    attachProtocol(server, secret, lease, touch, observe, close);
     try {
         await withLock(`${locksDirectory(projectRoot)}/cognition-runtime-start.lock`, async () => {
             const live = await liveLease(projectRoot);
@@ -213,16 +294,18 @@ export async function serveRuntime(startPath) {
     }
     heartbeat = setInterval(() => {
         lease.heartbeatAt = new Date().toISOString();
-        void writeLease(projectRoot, lease);
-    }, 5_000);
+        leaseWrite = leaseWrite.then(() => writeLease(projectRoot, lease)).catch(() => undefined);
+    }, heartbeatIntervalMs);
     poller = setInterval(() => {
-        void observer.observeNow();
-        void v1Synced(projectRoot).then((synced) => { if (!synced)
-            return reconcileV1State(projectRoot); });
-    }, pollIntervalMs);
-    touch();
+        void observe().catch(() => undefined);
+    }, runtimePollIntervalMs);
     await appendEvent(projectRoot, { type: 'runtime.started', source: { kind: 'cli', instanceId: lease.instanceId }, idempotencyKey: `runtime:started:${lease.instanceId}`, payload: {} });
-    await observer.observeNow();
+    if (currentPolicy.filesystemEventsEnabled)
+        filesystem.start();
+    await observe();
+    await writeLease(projectRoot, lease);
+    await rm(cognitionRuntimeStartupPath(projectRoot), { force: true });
+    touch();
     return { lease, close };
 }
 export async function runtimeStatus(startPath) {
@@ -240,8 +323,8 @@ export async function enableRuntime(startPath) {
     if (!await exists(cognitionManifestPath(projectRoot)))
         throw new Error('v2 migration is required before enabling the runtime');
     const current = await loadPolicy(projectRoot);
-    if (!current.enabled) {
-        await atomicWriteJson(cognitionPolicyPath(projectRoot), { ...current, enabled: true });
+    if (!current.enabled || !current.autoStart) {
+        await writeRuntimePolicy(projectRoot, { ...current, enabled: true, autoStart: true });
         await appendEvent(projectRoot, { type: 'runtime.enabled', source: { kind: 'cli' }, idempotencyKey: 'runtime:enabled', payload: {} });
     }
     return runtimeStatus(projectRoot);
@@ -252,25 +335,106 @@ export async function disableRuntime(startPath) {
         throw new Error('v2 migration is required before disabling the runtime');
     await stopRuntime(projectRoot);
     const current = await loadPolicy(projectRoot);
-    await atomicWriteJson(cognitionPolicyPath(projectRoot), { ...current, enabled: false });
+    await writeRuntimePolicy(projectRoot, { ...current, enabled: false, autoStart: false });
     return runtimeStatus(projectRoot);
 }
+export async function setFilesystemEvents(startPath, enabled) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    if (!await exists(cognitionManifestPath(projectRoot)))
+        throw new Error('v2 migration is required before configuring filesystem events');
+    const wasRunning = (await runtimeStatus(projectRoot)).running;
+    if (wasRunning)
+        await stopRuntime(projectRoot);
+    const current = await loadPolicy(projectRoot);
+    await writeRuntimePolicy(projectRoot, { ...current, filesystemEventsEnabled: enabled });
+    if (wasRunning)
+        return startRuntime(projectRoot);
+    return runtimeStatus(projectRoot);
+}
+async function waitForRuntime(projectRoot, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const status = await runtimeStatus(projectRoot);
+        if (status.running && !await loadStartupMarker(projectRoot))
+            return status;
+        await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    return null;
+}
+async function startRuntimeCoordinated(projectRoot, timeoutMs) {
+    const existing = await liveLease(projectRoot);
+    if (existing)
+        return runtimeStatus(projectRoot);
+    const attemptId = createInstanceId();
+    let owner = false;
+    try {
+        await withLock(`${locksDirectory(projectRoot)}/cognition-runtime-start.lock`, async () => {
+            const live = await liveLease(projectRoot);
+            if (live)
+                return;
+            const marker = await loadStartupMarker(projectRoot);
+            if (marker && Date.now() - Date.parse(marker.createdAt) <= startupMarkerTimeoutMs)
+                return;
+            await atomicWriteJson(cognitionRuntimeStartupPath(projectRoot), { attemptId, pid: process.pid, createdAt: new Date().toISOString() });
+            owner = true;
+        });
+    }
+    catch {
+        // Another process owns the startup lock; it will publish the lease or the marker will expire.
+    }
+    if (owner) {
+        const child = spawn(process.execPath, [cliPath, 'runtime', 'serve', '--path', projectRoot], { detached: true, stdio: 'ignore', windowsHide: true });
+        child.unref();
+    }
+    const status = await waitForRuntime(projectRoot, timeoutMs);
+    const marker = await loadStartupMarker(projectRoot);
+    if (marker?.attemptId === attemptId)
+        await rm(cognitionRuntimeStartupPath(projectRoot), { force: true });
+    if (status)
+        return status;
+    throw new Error('runtime failed to start');
+}
 export async function startRuntime(startPath) {
     const projectRoot = await resolveProjectRoot(startPath);
     const current = await loadPolicy(projectRoot);
     if (!current.enabled)
         throw new Error('runtime is disabled; run ctx runtime enable first');
+    const pending = startupPromises.get(projectRoot);
+    if (pending)
+        return pending;
+    const operation = startRuntimeCoordinated(projectRoot, 1_500).finally(() => startupPromises.delete(projectRoot));
+    startupPromises.set(projectRoot, operation);
+    return operation;
+}
+export async function ensureRuntimeForSession(startPath, options = {}) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    if (!await exists(cognitionManifestPath(projectRoot)))
+        return { projectRoot, started: false, running: false, skipped: 'not-migrated' };
+    const current = await loadPolicy(projectRoot);
+    if (!current.enabled || !current.autoStart || (options.source === 'claude-hook' && !current.allowHookStartup))
+        return { projectRoot, started: false, running: false, skipped: 'disabled' };
     if (await liveLease(projectRoot))
-        return runtimeStatus(projectRoot);
-    const child = spawn(process.execPath, [cliPath, 'runtime', 'serve', '--path', projectRoot], { detached: true, stdio: 'ignore', windowsHide: true });
-    child.unref();
-    for (let attempt = 0; attempt < 20; attempt += 1) {
-        await new Promise((resolve) => setTimeout(resolve, 50));
-        const status = await runtimeStatus(projectRoot);
-        if (status.running)
-            return status;
+        return { projectRoot, started: false, running: true, skipped: 'already-running' };
+    const pending = startupPromises.get(projectRoot);
+    if (pending) {
+        try {
+            const status = await pending;
+            return { projectRoot, started: false, running: status.running, skipped: 'startup-in-progress' };
+        }
+        catch {
+            return { projectRoot, started: false, running: false, skipped: 'unavailable' };
+        }
+    }
+    const operation = startRuntimeCoordinated(projectRoot, options.timeoutMs ?? 1_000)
+        .finally(() => startupPromises.delete(projectRoot));
+    startupPromises.set(projectRoot, operation);
+    try {
+        const status = await operation;
+        return { projectRoot, started: true, running: status.running, skipped: null };
+    }
+    catch {
+        return { projectRoot, started: false, running: false, skipped: 'unavailable' };
     }
-    throw new Error('runtime failed to start');
 }
 export async function stopRuntime(startPath) {
     const projectRoot = await resolveProjectRoot(startPath);
@@ -278,10 +442,10 @@ export async function stopRuntime(startPath) {
     if (!lease)
         return runtimeStatus(projectRoot);
     await request(projectRoot, lease, 'stop');
-    for (let attempt = 0; attempt < 20; attempt += 1) {
+    for (let attempt = 0; attempt < 40; attempt += 1) {
         await new Promise((resolve) => setTimeout(resolve, 50));
         const status = await runtimeStatus(projectRoot);
-        if (!status.running)
+        if (!status.running && !status.lease)
             return status;
     }
     throw new Error('runtime failed to stop');
@@ -293,3 +457,15 @@ export async function observeRuntime(startPath) {
         return false;
     return Boolean((await request(projectRoot, lease, 'observe'))?.ok);
 }
+export async function touchRuntime(startPath) {
+    try {
+        const projectRoot = await resolveProjectRoot(startPath);
+        const lease = await loadLease(projectRoot);
+        if (!lease)
+            return false;
+        return Boolean((await request(projectRoot, lease, 'ping'))?.ok);
+    }
+    catch {
+        return false;
+    }
+}