@nocville/npc 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,184 @@
+import type { StatusUpdate, AgentStats } from '@nocville/node';
+import type { NpcConfig, Status, Mood, BehaviorHints } from '../../core/types.js';
+/**
+ * Shared session plumbing for hook-driven AI-agent NPCs (Claude Code, Codex).
+ *
+ * Each agent session is one NPC. A hook invocation reads the session's state
+ * file, applies the event, writes the state back, and decides whether to push:
+ *
+ *  - phase changes (working ↔ waiting ↔ idle) and the first push go out at once;
+ *  - rapid same-phase activity changes (PreToolUse bursts) are coalesced so the
+ *    service stays well under the API rate limit, while the *latest* activity
+ *    still lands — a deferred flush pushes whatever the state is when it fires.
+ *
+ * Pushes run in a detached background process (`<agent> flush <session>`) so a
+ * hook returns in tens of milliseconds and never blocks or fails the agent.
+ */
+export type AgentPhase = 'IDLE' | 'WORKING' | 'WAITING';
+export interface AgentSessionState {
+    hookDeliveries?: {
+        key: string;
+        source: string;
+        at: number;
+    }[];
+    agentStats?: AgentStats;
+    /** Stop revision awaiting collection by a detached flush (including coalesced flushes). */
+    statsPendingRev?: number;
+    sessionId: string;
+    serviceId: string;
+    startedAt?: number;
+    agentPid?: number;
+    agentStartedAt?: number;
+    agentPidResolveAttempts?: number;
+    agentPidLastResolveAt?: number;
+    watchdogPid?: number;
+    /** First terminal delivery attempt, persisted across watchdog restarts. */
+    offlineRetryStartedAt?: number;
+    /** Terminal delivery exhausted its budget or received a non-retryable response. */
+    offlineDeliveryStopped?: boolean;
+    subagents?: Record<string, {
+        type: string;
+        activity: string;
+        at: number;
+    }>;
+    /** Machine phase. */
+    state: AgentPhase;
+    projectDir: string;
+    lastEvent: string;
+    lastUpdate: number;
+    /** Recent activity lines, most recent FIRST (desk-sign shows values[0]). */
+    activity?: string[];
+    /** Cached user-facing session name (Claude Code session title), if any. */
+    name?: string;
+    status?: Status;
+    mood?: Mood;
+    /** Offline sentinel pending push (session ended). */
+    offline?: boolean;
+    /** Monotonic revision bumped on every applied change. */
+    rev?: number;
+    /** Revision last pushed successfully. */
+    pushedRev?: number;
+    /** Epoch ms of the last push. */
+    lastPushAt?: number;
+    /** Epoch ms a deferred flush is scheduled for. */
+    flushAt?: number;
+}
+/** Result of applying one agent event. */
+export interface AgentTransition {
+    state: AgentPhase;
+    /** Current activity line; `undefined` keeps the previous one. */
+    activity?: string;
+    status: Status;
+    mood: Mood;
+    offline?: boolean;
+    /** Event carried nothing displayable — record it but never push for it. */
+    quiet?: boolean;
+}
+export interface StatusOutput {
+    status: Status;
+    mood: Mood;
+    message: string;
+    /** 'working' | 'waiting' | 'idle' | 'offline'. */
+    subStatus?: string;
+    behavior?: BehaviorHints;
+    offline?: boolean;
+}
+/** Behavior hints + subStatus for a phase (shared by every agent NPC). */
+export declare function phasePresentation(state: AgentPhase, offline?: boolean): {
+    subStatus: string;
+    behavior?: BehaviorHints;
+};
+/** Static identity of an agent integration. */
+export interface AgentAdapter {
+    /** CLI command name: 'claude-code' | 'codex'. */
+    command: string;
+    /** Banner prefix: 'Claude' | 'Codex'. */
+    label: string;
+    /** Appearance family sent as `appearance.family` (branded NPC tee + headgear). */
+    family: 'claude' | 'codex' | 'gemini' | 'cursor';
+    stateDir: string;
+    /** Heartbeat sent with each push — the server marks the NPC unknown at 2x. */
+    heartbeatSeconds: number;
+    processNames?: readonly string[];
+    /** A node ancestor must match this argv pattern; unrelated node processes never qualify. */
+    nodeCommandPattern?: RegExp;
+}
+export declare const ACTIVITY_HISTORY = 8;
+export declare const DEFAULT_MIN_PUSH_GAP_MS = 1500;
+export declare function projectNameOf(cwd: string): string;
+/** "Claude · nocville", clamped to the API's 32-char banner limit. */
+export declare function agentDisplayName(label: string, subject: string): string;
+/** Service ids are ≤100 chars of [A-Za-z0-9_.-]. */
+export declare function sanitizeServiceId(raw: string): string;
+export declare function stateFilePath(stateDir: string, sessionId: string): string;
+export declare function readSessionState(stateDir: string, sessionId: string): AgentSessionState | null;
+/** Atomic write (temp file + rename) so concurrent readers never see half a file. */
+export declare function writeSessionState(stateDir: string, state: AgentSessionState): void;
+export declare function deleteSessionState(stateDir: string, sessionId: string): void;
+/** Remove state files older than `maxAgeMs`. Returns the number removed. */
+export declare function cleanupSessionStates(stateDir: string, maxAgeMs: number, now?: number): Promise<number>;
+/** Cross-process hourly maintenance, invoked only on SessionStart. */
+export declare function maybeCleanupSessionStates(stateDir: string, now?: number): Promise<number>;
+/** Prepend `line` to the history (deduping an identical head), capped. */
+export declare function pushHistory(prev: string[] | undefined, line: string | undefined): string[];
+export interface ApplyInput {
+    sessionId: string;
+    serviceId: string;
+    projectDir: string;
+    eventName: string;
+    name?: string;
+    transition: AgentTransition;
+    now: number;
+}
+export type PushDecision = {
+    kind: 'none';
+} | {
+    kind: 'now';
+} | {
+    kind: 'defer';
+    delayMs: number;
+};
+/**
+ * Apply a transition to the previous state and decide when to push.
+ * Pure — exposed for testing.
+ */
+export declare function applyTransition(prev: AgentSessionState | null, input: ApplyInput, minGapMs?: number): {
+    next: AgentSessionState;
+    decision: PushDecision;
+};
+/** Build the status push for a session (offline sentinel when the session ended). */
+export declare function buildAgentPayload(adapter: AgentAdapter, state: AgentSessionState, config: Pick<NpcConfig, 'name' | 'map'>): StatusUpdate;
+export interface PushDeps {
+    /** Override the HTTP push (tests). */
+    push?: (serviceId: string, payload: StatusUpdate) => Promise<{
+        success: boolean;
+        error?: string;
+        statusCode?: number;
+    }>;
+    onResult?: (result: {
+        success: boolean;
+        error?: string;
+        statusCode?: number;
+    }) => void;
+    timeoutMs?: number;
+    force?: boolean;
+    lockWaitMs?: number;
+}
+/**
+ * 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 declare function flushSession(adapter: AgentAdapter, config: NpcConfig, sessionId: string, deps?: PushDeps): Promise<boolean>;
+/** Current parent activity, up to three subagents, then recent parent history. */
+export declare function tickerLines(state: AgentSessionState): string[];
+export declare function applySubagentEvent(prev: AgentSessionState, agentId: string, type: string, event: string, activity: string, now: number): AgentSessionState;
+/**
+ * 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 declare function spawnDetachedFlush(adapter: AgentAdapter, config: NpcConfig, sessionId: string, delayMs: number, cliPath?: string | undefined, stats?: boolean): void;
+export declare function spawnDetachedAgent(adapter: AgentAdapter, config: NpcConfig, args: string[], cliPath?: string | undefined): number | undefined;
+export declare function sleep(ms: number): Promise<void>;
+//# sourceMappingURL=session.d.ts.map

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

@@ -0,0 +1,368 @@
+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 { 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;
+            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 result = await push(state.serviceId, buildAgentPayload(adapter, state, 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, rev);
+                    fresh.lastPushAt = Date.now();
+                }
+                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