@nocville/npc 0.0.0-stage → 0.2.1

package/dist/npcs/agent-common/session.js

@@ -0,0 +1,390 @@
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+import { NocvilleClient } from '@nocville/node';
+import { loadSessionFilter, sessionPublishDecision, } from '../../core/session-filter.js';
+import { truncate } from '../../core/text.js';
+import { withStateLock } from './lock.js';
+/** Behavior hints + subStatus for a phase (shared by every agent NPC). */
+export function phasePresentation(state, offline) {
+    if (offline)
+        return { subStatus: 'offline' };
+    switch (state) {
+        case 'WORKING':
+            // Head to a desk and sit while actively working.
+            return { subStatus: 'working', behavior: { activity: 'busy', busy: 'seek-desk' } };
+        case 'WAITING':
+            // Freeze and raise a hand until the human responds.
+            return {
+                subStatus: 'waiting',
+                behavior: { activity: 'waiting', waitingEmote: 'raised-hand' },
+            };
+        case 'IDLE':
+        default:
+            // Settle at the desk and doze off.
+            return {
+                subStatus: 'idle',
+                behavior: { activity: 'idle', idle: 'stay', idlePose: 'sleep' },
+            };
+    }
+}
+export const ACTIVITY_HISTORY = 8;
+export const DEFAULT_MIN_PUSH_GAP_MS = 1500;
+const STATE_PREFIX = 'session-';
+// ---------------------------------------------------------------- naming
+export function projectNameOf(cwd) {
+    const parts = cwd.replace(/\\/g, '/').replace(/\/+$/, '').split('/');
+    return parts[parts.length - 1] || 'unknown';
+}
+/** "Claude · nocville", clamped to the API's 32-char banner limit. */
+export function agentDisplayName(label, subject) {
+    return truncate(`${label} · ${subject}`, 32);
+}
+/** Service ids are ≤100 chars of [A-Za-z0-9_.-]. */
+export function sanitizeServiceId(raw) {
+    return raw
+        .replace(/[^A-Za-z0-9_.-]+/g, '-')
+        .replace(/-+/g, '-')
+        .slice(0, 100);
+}
+// ---------------------------------------------------------------- state file
+export function stateFilePath(stateDir, sessionId) {
+    const safe = sessionId.replace(/[^A-Za-z0-9_.-]/g, '_');
+    return join(stateDir, `${STATE_PREFIX}${safe}.json`);
+}
+export function readSessionState(stateDir, sessionId) {
+    try {
+        const raw = JSON.parse(readFileSync(stateFilePath(stateDir, sessionId), 'utf-8'));
+        if (typeof raw['sessionId'] !== 'string')
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+/** Atomic write (temp file + rename) so concurrent readers never see half a file. */
+export function writeSessionState(stateDir, state) {
+    mkdirSync(stateDir, { recursive: true });
+    const path = stateFilePath(stateDir, state.sessionId);
+    const tmp = `${path}.${process.pid}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+    writeFileSync(tmp, JSON.stringify(state), 'utf-8');
+    renameSync(tmp, path);
+}
+export function deleteSessionState(stateDir, sessionId) {
+    const path = stateFilePath(stateDir, sessionId);
+    if (existsSync(path)) {
+        try {
+            rmSync(path);
+        }
+        catch {
+            // best effort
+        }
+    }
+}
+/** Remove state files older than `maxAgeMs`. Returns the number removed. */
+export async function cleanupSessionStates(stateDir, maxAgeMs, now = Date.now()) {
+    if (!existsSync(stateDir))
+        return 0;
+    let removed = 0;
+    for (const file of readdirSync(stateDir)) {
+        if (!file.startsWith(STATE_PREFIX) || !file.endsWith('.json'))
+            continue;
+        const path = join(stateDir, file);
+        try {
+            if (now - statSync(path).mtimeMs <= maxAgeMs)
+                continue;
+            // Recheck under the same lock as hooks, so a SessionStart cannot be deleted mid-write.
+            await withStateLock(path, () => {
+                if (now - statSync(path).mtimeMs > maxAgeMs) {
+                    unlinkSync(path);
+                    removed++;
+                }
+            }, 0);
+        }
+        catch {
+            /* active writer, missing file or filesystem error: leave it alone */
+        }
+    }
+    return removed;
+}
+/** Cross-process hourly maintenance, invoked only on SessionStart. */
+export async function maybeCleanupSessionStates(stateDir, now = Date.now()) {
+    const marker = join(stateDir, '.last-cleanup');
+    try {
+        return await withStateLock(marker, async () => {
+            let last = NaN;
+            try {
+                last = Number(readFileSync(marker, 'utf8'));
+            }
+            catch {
+                /* first cleanup */
+            }
+            if (Number.isFinite(last) && now - last < 3_600_000)
+                return 0;
+            const removed = await cleanupSessionStates(stateDir, 86_400_000, now);
+            writeFileSync(marker, String(now), { mode: 0o600 });
+            return removed;
+        }, 0);
+    }
+    catch {
+        return 0;
+    }
+}
+/** Prepend `line` to the history (deduping an identical head), capped. */
+export function pushHistory(prev, line) {
+    const list = [...(prev ?? [])];
+    if (line && list[0] !== line)
+        list.unshift(line);
+    return list.slice(0, ACTIVITY_HISTORY);
+}
+/**
+ * Apply a transition to the previous state and decide when to push.
+ * Pure — exposed for testing.
+ */
+export function applyTransition(prev, input, minGapMs = DEFAULT_MIN_PUSH_GAP_MS) {
+    const t = input.transition;
+    const history = pushHistory(prev?.activity, t.activity);
+    const prevHead = prev?.activity?.[0];
+    const subagents = pruneSubagents(prev?.subagents, input.now);
+    const changed = !prev ||
+        prev.state !== t.state ||
+        prev.status !== t.status ||
+        Object.keys(subagents).length !== Object.keys(prev.subagents ?? {}).length ||
+        history[0] !== prevHead ||
+        !!t.offline !== !!prev.offline ||
+        (input.name !== undefined && input.name !== prev.name);
+    const rev = (prev?.rev ?? 0) + (changed ? 1 : 0);
+    const next = {
+        ...prev,
+        sessionId: input.sessionId,
+        startedAt: prev?.startedAt ?? input.now,
+        serviceId: prev?.serviceId ?? input.serviceId,
+        state: t.state,
+        projectDir: input.projectDir,
+        lastEvent: input.eventName,
+        lastUpdate: input.now,
+        activity: history,
+        subagents,
+        name: input.name ?? prev?.name,
+        status: t.status,
+        mood: t.mood,
+        offline: t.offline || undefined,
+        rev,
+        pushedRev: prev?.pushedRev ?? 0,
+        lastPushAt: prev?.lastPushAt ?? 0,
+        flushAt: prev?.flushAt,
+    };
+    if (t.offline)
+        return { next, decision: { kind: 'now' } };
+    if (t.quiet || !changed)
+        return { next, decision: { kind: 'none' } };
+    const phaseChanged = !prev || prev.state !== t.state || !prev.lastPushAt;
+    const sinceLast = input.now - (next.lastPushAt ?? 0);
+    if (phaseChanged || sinceLast >= minGapMs) {
+        // Stamp the push time now: the push itself runs asynchronously (detached),
+        // and the next hook must already see it to coalesce.
+        next.lastPushAt = input.now;
+        return { next, decision: { kind: 'now' } };
+    }
+    // Coalesce: a flush is already pending (and not stale) → it will pick up this rev.
+    if (next.flushAt && next.flushAt > input.now - 2000)
+        return { next, decision: { kind: 'none' } };
+    const delayMs = Math.max(50, minGapMs - sinceLast);
+    next.flushAt = input.now + delayMs;
+    return { next, decision: { kind: 'defer', delayMs } };
+}
+// ---------------------------------------------------------------- push
+/** Build the status push for a session (offline sentinel when the session ended). */
+export function buildAgentPayload(adapter, state, config) {
+    const subject = state.name ?? projectNameOf(state.projectDir);
+    const name = config.name ? truncate(config.name, 32) : agentDisplayName(adapter.label, subject);
+    const current = state.activity?.[0] ?? '';
+    const { subStatus, behavior } = phasePresentation(state.state, state.offline);
+    if (state.offline) {
+        return {
+            status: 'unknown',
+            mood: 'idle',
+            name,
+            message: 'Session ended',
+            subStatus,
+            offline: true,
+            map: config.map,
+        };
+    }
+    const screenData = {
+        layout: 'ticker',
+        values: tickerLines({ ...state, subagents: pruneSubagents(state.subagents, Date.now()) }).map((a) => ({ label: '', value: a })),
+    };
+    return {
+        status: state.status ?? 'healthy',
+        mood: state.mood ?? 'happy',
+        name,
+        message: current ? truncate(current, 120) : undefined,
+        archetype: 'ai-agent',
+        metrics: { sessionStartedAt: state.startedAt ?? state.lastUpdate },
+        appearance: { family: adapter.family },
+        agentStats: state.agentStats,
+        subStatus,
+        behavior,
+        alertConfig: { heartbeatInterval: state.watchdogPid ? adapter.heartbeatSeconds : 3600 },
+        screenData,
+        companion: {
+            screenType: 'desk-sign',
+            size: { w: 3, h: 1 },
+            placement: 'on-desk',
+            label: truncate(projectNameOf(state.projectDir), 40),
+        },
+        map: config.map,
+    };
+}
+async function defaultPush(config, serviceId, payload, timeoutMs) {
+    const client = new NocvilleClient({
+        apiUrl: config.apiUrl,
+        apiKey: config.apiKey,
+        serviceId,
+        timeout: timeoutMs,
+        retries: 0,
+        debug: config.debug,
+    });
+    return client.pushStatus(payload);
+}
+/**
+ * Push the session's current state if it has unpushed changes (or is offline),
+ * then record the push. Re-reads the state right before writing so a hook that
+ * ran concurrently isn't clobbered. Never throws.
+ */
+export async function flushSession(adapter, config, sessionId, deps = {}) {
+    const path = stateFilePath(adapter.stateDir, sessionId);
+    try {
+        // Serialize HTTP delivery separately: hooks can update state throughout a request,
+        // but an older delivery can never arrive after a newer/offline one.
+        return await withStateLock(`${path}.push`, async () => {
+            const state = readSessionState(adapter.stateDir, sessionId);
+            if (!state || !config.apiKey || state.offlineDeliveryStopped)
+                return false;
+            const rev = state.rev ?? 0;
+            const verdict = sessionPublishDecision(deps.sessionFilter ?? loadSessionFilter(), {
+                projectDir: state.projectDir,
+                name: state.name,
+            });
+            // Filtered out (sessions.json). Never shown: consume the revision so nothing retries.
+            // Already shown (e.g. renamed into the denylist): despawn it once, then go quiet.
+            // Checked on every push, so later edits to the file take effect without reinstalling.
+            if (!verdict.publish && !state.published) {
+                await withStateLock(path, () => {
+                    const fresh = readSessionState(adapter.stateDir, sessionId);
+                    if (!fresh)
+                        return;
+                    fresh.pushedRev = Math.max(fresh.pushedRev ?? 0, fresh.rev ?? 0);
+                    fresh.flushAt = undefined;
+                    writeSessionState(adapter.stateDir, fresh);
+                }, deps.lockWaitMs);
+                return true;
+            }
+            const despawnFiltered = !verdict.publish;
+            if (!deps.force && rev <= (state.pushedRev ?? 0)) {
+                await withStateLock(path, () => {
+                    const fresh = readSessionState(adapter.stateDir, sessionId);
+                    if (fresh && (fresh.rev ?? 0) === rev) {
+                        fresh.flushAt = undefined;
+                        writeSessionState(adapter.stateDir, fresh);
+                    }
+                }, deps.lockWaitMs);
+                return false;
+            }
+            const push = deps.push ??
+                ((sid, payload) => defaultPush(config, sid, payload, deps.timeoutMs ?? 4000));
+            let ok = false;
+            try {
+                const shown = despawnFiltered ? { ...state, offline: true } : state;
+                const result = await push(state.serviceId, buildAgentPayload(adapter, shown, config));
+                ok = result.success;
+                deps.onResult?.(result);
+            }
+            catch {
+                /* retry on next hook/watchdog tick */
+            }
+            await withStateLock(path, () => {
+                const fresh = readSessionState(adapter.stateDir, sessionId);
+                if (!fresh)
+                    return;
+                // Retain terminal state until cleanup so late hooks/watchers cannot revive it.
+                if (ok) {
+                    fresh.pushedRev = Math.max(fresh.pushedRev ?? 0, despawnFiltered ? (fresh.rev ?? 0) : rev);
+                    fresh.lastPushAt = Date.now();
+                    fresh.published = !despawnFiltered && !state.offline;
+                }
+                if (!fresh.flushAt || fresh.flushAt <= Date.now())
+                    fresh.flushAt = undefined;
+                writeSessionState(adapter.stateDir, fresh);
+            }, deps.lockWaitMs);
+            return ok;
+        }, deps.lockWaitMs ?? 6000);
+    }
+    catch {
+        return false;
+    }
+}
+/** Current parent activity, up to three subagents, then recent parent history. */
+export function tickerLines(state) {
+    const history = state.activity ?? [];
+    const agents = Object.values(state.subagents ?? {})
+        .sort((a, b) => b.at - a.at)
+        .slice(0, 3)
+        .map((entry) => `↳ ${entry.type}: ${entry.activity}`);
+    return [...history.slice(0, 1), ...agents, ...history.slice(1)].slice(0, ACTIVITY_HISTORY);
+}
+export function applySubagentEvent(prev, agentId, type, event, activity, now) {
+    const subagents = pruneSubagents(prev.subagents, now);
+    if (event === 'Stop' || event === 'SubagentStop')
+        delete subagents[agentId];
+    else if (event === 'PreToolUse')
+        subagents[agentId] = { type, activity, at: now };
+    const next = { ...prev, subagents, lastUpdate: now, lastEvent: event };
+    if (JSON.stringify(tickerLines(prev)) !== JSON.stringify(tickerLines(next)))
+        next.rev = (prev.rev ?? 0) + 1;
+    return next;
+}
+/**
+ * Hand a flush to a detached background process so the hook can exit at once.
+ * The child inherits the resolved config via env (not argv, so the key never
+ * shows up in `ps`).
+ */
+export function spawnDetachedFlush(adapter, config, sessionId, delayMs, cliPath = process.argv[1], stats = false) {
+    spawnDetachedAgent(adapter, config, ['flush', sessionId, `--delay=${Math.round(delayMs)}`, ...(stats ? ['--stats'] : [])], cliPath);
+}
+export function spawnDetachedAgent(adapter, config, args, cliPath = process.argv[1]) {
+    if (!cliPath)
+        return undefined;
+    const env = { ...process.env };
+    env['NOCVILLE_API_URL'] = config.apiUrl;
+    env['NOCVILLE_API_KEY'] = config.apiKey;
+    if (config.map)
+        env['NOCVILLE_MAP'] = config.map;
+    if (config.name)
+        env['NOCVILLE_NAME'] = config.name;
+    try {
+        const child = spawn(process.execPath, [cliPath, adapter.command, ...args], {
+            detached: true,
+            stdio: 'ignore',
+            env,
+            windowsHide: true,
+        });
+        child.on('error', () => {
+            /* swallow — never fail the agent */
+        });
+        child.unref();
+        return child.pid;
+    }
+    catch {
+        // swallow
+    }
+}
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function pruneSubagents(subagents, now) {
+    return Object.fromEntries(Object.entries(subagents ?? {}).filter(([, value]) => now - value.at < 600_000));
+}
+//# sourceMappingURL=session.js.map

package/dist/npcs/agent-common/shim.d.ts

@@ -0,0 +1,4 @@
+export declare const SHIM_PATH: () => string;
+export declare const RUNTIME_POINTER: () => string;
+export declare function installHookShim(nodePath: string, cliPath: string): string;
+//# sourceMappingURL=shim.d.ts.map

package/dist/npcs/agent-common/shim.js

@@ -0,0 +1,90 @@
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { userConfigPath } from '../../core/user-config.js';
+import { pruneOldRuntimes } from './runtime.js';
+export const SHIM_PATH = () => join(dirname(userConfigPath()), 'bin', 'nocville-hook');
+export const RUNTIME_POINTER = () => join(dirname(userConfigPath()), 'runtime', 'current.json');
+function writeChanged(path, content, mode) {
+    try {
+        if (readFileSync(path, 'utf8') === content)
+            return;
+    }
+    catch {
+        /* first install */
+    }
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, content, { mode });
+    renameSync(tmp, path);
+}
+// Resolve relative to the shim itself, including custom XDG/NOCVILLE_CONFIG installs.
+// JSON is parsed by Node, never interpolated into shell code or decoded with sed.
+const SHIM = `#!/bin/sh
+# nocville-npc-hook: stable one-way hook launcher
+DIR=$(CDPATH= cd -- "$(dirname -- "$0")" 2>/dev/null && pwd) || exit 0
+IFS= read -r NODE < "$DIR/../runtime/node-path" 2>/dev/null || NODE=''
+if [ ! -x "$NODE" ]; then NODE=$(command -v node 2>/dev/null); fi
+for candidate in "$NODE" /opt/homebrew/bin/node /usr/local/bin/node "$HOME/.volta/bin/node"; do
+  if [ -x "$candidate" ]; then NODE="$candidate"; break; fi
+done
+if [ ! -x "$NODE" ]; then cat >/dev/null; if { [ "$1" = gemini ] || [ "$1" = cursor ] || [ "$1" = claude-code ]; }; then printf '{}\\n'; fi; exit 0; fi
+exec "$NODE" "$DIR/launch.cjs" "$DIR/../runtime/current.json" "$@"
+`;
+// Without Node, return a neutral empty object for both Claude and imported Cursor.
+// No payload is evaluated by either shell. Native Codex remains silent.
+const WINDOWS_SHIM = String.raw `@echo off
+setlocal DisableDelayedExpansion
+set "NOCVILLE_NODE="
+set /p "NOCVILLE_NODE="<"%~dp0..\runtime\node-path" 2>nul
+if exist "%NOCVILLE_NODE%" goto launch
+set "NOCVILLE_NODE="
+for /f "delims=" %%N in ('where node.exe 2^>nul') do if not defined NOCVILLE_NODE set "NOCVILLE_NODE=%%N"
+if not defined NOCVILLE_NODE goto no_node
+:launch
+"%NOCVILLE_NODE%" "%~dp0launch.cjs" "%~dp0..\runtime\current.json" %*
+exit /b 0
+:no_node
+more >nul
+if "%~1"=="cursor" echo {}
+if "%~1"=="gemini" echo {}
+if "%~1"=="claude-code" echo {}
+exit /b 0
+`;
+const LAUNCHER = `// Stable bootstrap. Hooks never return decisions or emit launcher errors.
+const fs = require('node:fs');
+const { spawnSync } = require('node:child_process');
+const agent = process.argv[3];
+const hook = !process.argv[4] || process.argv[4] === 'hook';
+let neutral = hook && (agent === 'gemini' || agent === 'cursor');
+let input = Buffer.alloc(0);
+try {
+  input = fs.readFileSync(0);
+  if (hook && agent === 'claude-code') {
+    try {
+      const event = JSON.parse(input.toString('utf8'));
+      const transcript = typeof event?.transcript_path === 'string' ? event.transcript_path.replace(/\\\\/g, '/') : '';
+      neutral = typeof event?.cursor_version === 'string' ||
+        (typeof event?.conversation_id === 'string' && !/(?:^|\\/)\\.claude(?:\\/|$)/.test(transcript));
+    } catch {}
+  }
+  const pointer = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+  if (typeof pointer.cli !== 'string' || !fs.existsSync(pointer.cli)) throw new Error('missing runtime');
+  const node = typeof pointer.node === 'string' && fs.existsSync(pointer.node) ? pointer.node : process.execPath;
+  // Buffer stdin once for payload-based imported-Cursor detection, then replay it unchanged.
+  // Never forward child stdout, even in debug mode or on an unexpected failure.
+  spawnSync(node, [pointer.cli, ...process.argv.slice(3)], { input, stdio: ['pipe', 'ignore', 'inherit'], windowsHide: true });
+} catch {}
+if (neutral) process.stdout.write('{}\\n');
+`;
+export function installHookShim(nodePath, cliPath) {
+    writeChanged(RUNTIME_POINTER(), JSON.stringify({ node: nodePath, cli: cliPath }, null, 2) + '\n', 0o600);
+    writeChanged(join(dirname(RUNTIME_POINTER()), 'node-path'), nodePath + '\n', 0o600);
+    writeChanged(join(dirname(SHIM_PATH()), 'launch.cjs'), LAUNCHER, 0o600);
+    writeChanged(SHIM_PATH(), SHIM, 0o755);
+    chmodSync(SHIM_PATH(), 0o755);
+    // Both launchers use the same bootstrap, including imported-Cursor detection.
+    writeChanged(SHIM_PATH() + '.cmd', WINDOWS_SHIM.replace(/\n/g, '\r\n'), 0o755);
+    pruneOldRuntimes(dirname(RUNTIME_POINTER()));
+    return SHIM_PATH();
+}
+//# sourceMappingURL=shim.js.map

package/dist/npcs/agent-common/watchdog.d.ts

@@ -0,0 +1,16 @@
+import type { NpcConfig } from '../../core/types.js';
+import { isAgentAlive } from './liveness.js';
+import type { AgentAdapter, PushDeps } from './session.js';
+export declare const WATCHDOG_TICK_MS = 15000;
+export declare const WATCHDOG_HEARTBEAT_MS = 60000;
+export declare const WATCHDOG_OFFLINE_RETRY_MS: number;
+export declare function ensureWatchdog(adapter: AgentAdapter, config: NpcConfig, sessionId: string, cliPath?: string, lockWaitMs?: number): Promise<void>;
+export interface WatchdogDeps extends PushDeps {
+    isAlive?: typeof isAgentAlive;
+    selfPid?: number;
+    now?: () => number;
+    wait?: (ms: number) => Promise<void>;
+}
+/** Silent, read-only observer of the agent process; never sends input to it. */
+export declare function runWatchdog(adapter: AgentAdapter, config: NpcConfig, sessionId: string | undefined, deps?: WatchdogDeps): Promise<void>;
+//# sourceMappingURL=watchdog.d.ts.map

package/dist/npcs/agent-common/watchdog.js

@@ -0,0 +1,144 @@
+import { isAgentAlive } from './liveness.js';
+import { withStateLock } from './lock.js';
+import { flushSession, readSessionState, sleep, spawnDetachedAgent, stateFilePath, writeSessionState, } from './session.js';
+export const WATCHDOG_TICK_MS = 15_000;
+export const WATCHDOG_HEARTBEAT_MS = 60_000;
+export const WATCHDOG_OFFLINE_RETRY_MS = 15 * 60_000;
+export async function ensureWatchdog(adapter, config, sessionId, cliPath, lockWaitMs) {
+    if (adapter.processNames?.length === 0 ||
+        !config.apiKey ||
+        process.env['NOCVILLE_NO_WATCHDOG'] === '1')
+        return;
+    await withStateLock(stateFilePath(adapter.stateDir, sessionId), () => {
+        const state = readSessionState(adapter.stateDir, sessionId);
+        // No heartbeat without proven liveness. Keep the long fallback on unsupported hosts.
+        if (!state || state.offline || !state.agentPid)
+            return;
+        if (state.watchdogPid && isAgentAlive({ pid: state.watchdogPid }))
+            return;
+        const pid = spawnDetachedAgent(adapter, config, ['watchdog', sessionId], cliPath);
+        if (pid) {
+            state.watchdogPid = pid;
+            writeSessionState(adapter.stateDir, state);
+        }
+    }, lockWaitMs);
+}
+/** Silent, read-only observer of the agent process; never sends input to it. */
+export async function runWatchdog(adapter, config, sessionId, deps = {}) {
+    if (!sessionId || adapter.processNames?.length === 0)
+        return;
+    const isAlive = deps.isAlive ?? isAgentAlive;
+    const now = deps.now ?? Date.now;
+    const wait = deps.wait ?? sleep;
+    const selfPid = deps.selfPid ?? process.pid;
+    let unknownTicks = 0;
+    let rejected = false;
+    let heartbeatRejected = false;
+    const delivery = {
+        ...deps,
+        onResult: (result) => {
+            if (!result.success && [400, 401, 403, 404].includes(result.statusCode ?? 0))
+                rejected = true;
+            deps.onResult?.(result);
+        },
+    };
+    // Do not clear a replacement observer's ownership. A failed write retries on the next tick.
+    const finish = async (terminal = false, abandoned = false) => {
+        await withStateLock(stateFilePath(adapter.stateDir, sessionId), () => {
+            const fresh = readSessionState(adapter.stateDir, sessionId);
+            if (!fresh || (fresh.watchdogPid && fresh.watchdogPid !== selfPid))
+                return;
+            if (terminal && !fresh.offline) {
+                fresh.offline = true;
+                fresh.rev = (fresh.rev ?? 0) + 1;
+            }
+            if (abandoned)
+                fresh.offlineDeliveryStopped = true;
+            fresh.watchdogPid = undefined;
+            writeSessionState(adapter.stateDir, fresh);
+        });
+    };
+    for (;;) {
+        await wait(WATCHDOG_TICK_MS);
+        try {
+            const state = readSessionState(adapter.stateDir, sessionId);
+            if (!state)
+                return;
+            if (state.watchdogPid && state.watchdogPid !== selfPid)
+                return;
+            if (rejected || state.offlineDeliveryStopped) {
+                await finish(true, true);
+                return;
+            }
+            if (heartbeatRejected) {
+                await finish();
+                return;
+            }
+            if (!state.offline && !state.agentPid) {
+                if (++unknownTicks >= 3) {
+                    await finish();
+                    return;
+                }
+                continue;
+            }
+            const terminal = state.offline || !isAlive({ pid: state.agentPid, startedAt: state.agentStartedAt });
+            if (terminal) {
+                if (state.offline && (state.pushedRev ?? 0) >= (state.rev ?? 0)) {
+                    await finish();
+                    return;
+                }
+                const startedAt = await withStateLock(stateFilePath(adapter.stateDir, sessionId), () => {
+                    const fresh = readSessionState(adapter.stateDir, sessionId);
+                    if (!fresh ||
+                        fresh.agentPid !== state.agentPid ||
+                        (fresh.watchdogPid && fresh.watchdogPid !== selfPid))
+                        return undefined;
+                    if (!fresh.offline) {
+                        fresh.offline = true;
+                        fresh.rev = (fresh.rev ?? 0) + 1;
+                    }
+                    fresh.offlineRetryStartedAt ??= now();
+                    writeSessionState(adapter.stateDir, fresh);
+                    return fresh.offlineRetryStartedAt;
+                });
+                if (startedAt === undefined)
+                    continue;
+                if (now() - startedAt >= WATCHDOG_OFFLINE_RETRY_MS) {
+                    await finish(true, true);
+                    return;
+                }
+                if (await flushSession(adapter, config, sessionId, delivery)) {
+                    await finish();
+                    return;
+                }
+            }
+            else if ((state.rev ?? 0) > (state.pushedRev ?? 0) ||
+                now() - (state.lastPushAt ?? 0) >= WATCHDOG_HEARTBEAT_MS) {
+                await flushSession(adapter, config, sessionId, {
+                    ...deps,
+                    force: true,
+                    onResult: (result) => {
+                        if (!result.success && [400, 401, 403, 404].includes(result.statusCode ?? 0))
+                            heartbeatRejected = true;
+                        deps.onResult?.(result);
+                    },
+                });
+                if (heartbeatRejected) {
+                    // A rejected heartbeat is not evidence the agent died. A later hook
+                    // can restart observation after credentials/routing recover.
+                    await finish();
+                    return;
+                }
+            }
+            if (rejected) {
+                await finish(true, true);
+                return;
+            }
+        }
+        catch {
+            // A transient state-lock/filesystem error must not kill an otherwise live observer.
+            continue;
+        }
+    }
+}
+//# sourceMappingURL=watchdog.js.map

package/dist/npcs/claude-code/defaults.d.ts

@@ -0,0 +1,15 @@
+export declare const DEFAULTS: {
+    stateDir: string;
+    stateFilePrefix: string;
+    stateFileMaxAge: number;
+    httpTimeout: number;
+    /** Watchdog-backed sessions become unknown after three minutes without a heartbeat. */
+    heartbeatSeconds: number;
+    /** Number of recent activity lines kept in the desk-sign ticker. */
+    activityBufferSize: number;
+    /** Coalesce same-phase activity pushes closer together than this. */
+    minPushGapMs: number;
+    /** Per-hook timeout written into settings.json (seconds) — a safety net only. */
+    hookTimeoutSeconds: number;
+};
+//# sourceMappingURL=defaults.d.ts.map

package/dist/npcs/claude-code/defaults.js

@@ -0,0 +1,17 @@
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+export const DEFAULTS = {
+    stateDir: join(tmpdir(), 'nocville-claude-code'),
+    stateFilePrefix: 'session-',
+    stateFileMaxAge: 24 * 60 * 60 * 1000, // 24 hours
+    httpTimeout: 4000,
+    /** Watchdog-backed sessions become unknown after three minutes without a heartbeat. */
+    heartbeatSeconds: 90,
+    /** Number of recent activity lines kept in the desk-sign ticker. */
+    activityBufferSize: 8,
+    /** Coalesce same-phase activity pushes closer together than this. */
+    minPushGapMs: 1500,
+    /** Per-hook timeout written into settings.json (seconds) — a safety net only. */
+    hookTimeoutSeconds: 10,
+};
+//# sourceMappingURL=defaults.js.map