fluffy-context 0.6.0 → 0.7.6

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/projections.js

@@ -37,6 +37,17 @@ function recordId(record, kind) {
     const field = kind === 'note' ? 'noteId' : kind === 'knowledge' ? 'knowledgeId' : 'deadendId';
     return typeof record[field] === 'string' ? record[field] : null;
 }
+function pathFocusFrom(event) {
+    const payload = event.payload;
+    if (payload.schemaVersion !== 1 || !Array.isArray(payload.paths))
+        return [];
+    return [...new Set(payload.paths
+            .filter((value) => typeof value === 'string')
+            .map((value) => value.replaceAll('\\', '/'))
+            .filter((value) => value.length > 0 && !value.startsWith('/') && !value.includes('\0') && !value.split('/').includes('..')))]
+        .sort()
+        .slice(-100);
+}
 function latestOpenObservationIds(events, notes) {
     const latest = new Map();
     for (const event of events) {
@@ -70,7 +81,7 @@ export function projectEvents(events) {
                 workspace.activeContextRef = contextRef;
             }
         }
-        if (event.type === 'note.recorded' && record) {
+        if (['note.recorded', 'note.resolved', 'note.absorbed'].includes(event.type) && record) {
             const noteId = recordId(record, 'note');
             if (noteId)
                 projection.notes[noteId] = payload;
@@ -88,6 +99,9 @@ export function projectEvents(events) {
         if (event.type === 'note.recorded' && openObservationIds.has(event.eventId)) {
             workspace.openObservationEventIds = [...workspace.openObservationEventIds, event.eventId].slice(-50);
         }
+        if (event.type === 'workspace.paths.changed') {
+            workspace.pathFocus = [...new Set([...workspace.pathFocus, ...pathFocusFrom(event)])].sort().slice(-100);
+        }
         projection.workspaces[key] = workspace;
     }
     return projection;

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;
+    }
+}

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

@@ -32,6 +32,7 @@ export interface CognitionEvent<T = Record<string, unknown>> {
 export interface CognitionRuntimePolicy {
     schemaVersion: 2;
     enabled: boolean;
+    autoStart: boolean;
     allowHookStartup: boolean;
     inactivityTimeoutMs: number;
     promptIntentMaxChars: number;
@@ -141,6 +142,21 @@ export interface CognitionRecordPayload<T extends Record<string, unknown> = Reco
     sourceHash?: string;
     anchorProvenance?: 'snapshot' | 'live' | 'global';
 }
+export interface WorkspacePathChange {
+    path: string;
+    kind: 'created' | 'modified' | 'deleted' | 'renamed' | 'unknown';
+    fileType: 'file';
+    sizeBytes?: number;
+    mtimeMs?: number;
+}
+export interface WorkspacePathsChangedPayload {
+    schemaVersion: 1;
+    paths: string[];
+    changes: WorkspacePathChange[];
+    pathCount: number;
+    coalesced: boolean;
+    truncated: boolean;
+}
 export interface CognitionProjection {
     schemaVersion: 2;
     contexts: Record<string, CognitionRecordPayload>;

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

@@ -2,11 +2,12 @@ import crypto from 'node:crypto';
 import path from 'node:path';
 import { access, readFile, readdir } from 'node:fs/promises';
 import { readGitWorktreeState } from '../git/git-adapter.js';
-import { cognitionManifestPath, cognitionPolicyPath, cognitionV1SyncPath, contextsRoot, deadendsPath, knowledgePath, notesPath, snapshotsDirectory } from '../storage/layout.js';
+import { cognitionManifestPath, cognitionV1SyncPath, contextsRoot, deadendsPath, knowledgePath, notesPath, snapshotsDirectory } from '../storage/layout.js';
 import { readJson } from '../storage/json-store.js';
 import { atomicWriteJson } from '../storage/atomic-write.js';
 import { appendEvent } from './journal.js';
 import { rebuildProjections } from './projections.js';
+import { loadRuntimePolicy } from './policy.js';
 function digest(record) {
     return crypto.createHash('sha256').update(JSON.stringify(record)).digest('hex');
 }
@@ -34,7 +35,7 @@ export async function v1Synced(projectRoot) {
 async function enabled(projectRoot) {
     try {
         await access(cognitionManifestPath(projectRoot));
-        return (await readJson(cognitionPolicyPath(projectRoot))).enabled;
+        return (await loadRuntimePolicy(projectRoot)).enabled;
     }
     catch {
         return false;

package/dist/src/compiler/activity.d.ts

@@ -0,0 +1,3 @@
+import type { BranchWorkspace, CognitionEvent } from '../cognition/types.js';
+import type { ContextActivityRecord, ContextAnchor } from './types.js';
+export declare function extractActivity(projectRoot: string, events: CognitionEvent[], anchor: ContextAnchor, workspace: BranchWorkspace | null, limit: number): Promise<ContextActivityRecord[]>;