@maolon/pi-watcher 0.0.0-stage → 0.1.1

package/dist/engine/tool-actions.js

@@ -0,0 +1,348 @@
+/**
+ * Action dispatch + LLM projection layer for the watcher tool (design 11.4 service surface).
+ * Reused by two backends: the local primary calls it directly; attached sessions run it in the primary over IPC.
+ *
+ * Projection principle: the model only needs the minimum facts required for decisions -- do not echo the spec it submitted,
+ * and do not expose internal bookkeeping fields (owner path / digest / generation / receipt JSON).
+ * Full facts remain in SQLite and the /watcher panel (human debugging view).
+ */
+import { checkRunId } from '../source/agent-check/adapter.js';
+import { fileRunId } from '../source/agent-file/adapter.js';
+import { DEFAULT_ATTENTION_TTL_MS } from './engine.js';
+import * as pathMod from 'node:path';
+/** Active lifecycle filter set shared by list/watch dedup */
+const ACTIVE_LIFECYCLES = ['active', 'paused'];
+const rec = (v) => (v !== null && typeof v === 'object' ? v : {});
+const str = (v) => (typeof v === 'string' && v !== '' ? v : undefined);
+const num = (v) => (typeof v === 'number' ? v : undefined);
+const arr = (v) => (Array.isArray(v) ? v : []);
+const compact = (v) => JSON.parse(JSON.stringify(v)); // drop undefined
+function projectList(v) {
+    const r = rec(v);
+    const watches = arr(r.items).map(it => {
+        const w = rec(it);
+        const t = rec(w.target);
+        return {
+            watchId: str(w.watchId),
+            runId: str(t.runId),
+            taskState: str(w.taskState) ?? 'unknown',
+            lifecycle: str(w.lifecycle),
+            health: str(w.health),
+            openEpisodes: num(w.openEpisodes) ?? 0
+        };
+    });
+    const out = {
+        watches,
+        terminalCount: num(r.terminalCount) ?? 0,
+        relay: str(rec(r.relay).transport) ?? 'local-display'
+    };
+    const next = str(r.nextCursor);
+    if (next)
+        out.nextCursor = next;
+    return out;
+}
+/**
+ * Log tail formatting and hard limits (design 11.4 evidence economy):
+ * 1. Filter out non-string lines; take at most the last 8 lines.
+ * 2. Truncate each line to 300 characters (prevents oversized JSON / ARGV / stack traces from blowing up context).
+ * 3. Hard-truncate total volume to 1000 characters (if over, keep the newest tail and add a truncation marker).
+ * 4. Fully replaces the old tailLines array to avoid echoing twice.
+ */
+function formatLatestOutput(rawLines) {
+    const lines = rawLines.filter((l) => typeof l === 'string');
+    if (lines.length === 0)
+        return undefined;
+    const sliced = lines.slice(-8).map(l => (l.length > 300 ? l.slice(0, 297) + '...' : l));
+    const joined = sliced.join('\n');
+    if (joined.length <= 1000)
+        return joined;
+    return '[... output truncated ...]\n' + joined.slice(-900);
+}
+function projectInspect(v) {
+    const r = rec(v);
+    const spec = rec(r.watch);
+    const mission = rec(spec.mission);
+    const snap = rec(r.snapshot);
+    const openEpisodes = arr(r.episodes)
+        .filter(e0 => rec(e0).state === 'open')
+        .map(e0 => {
+        const e = rec(e0);
+        const b = rec(e.body);
+        return compact({
+            kind: str(e.kind),
+            reason: str(b.reasonCode) ?? str(b.summary) ?? str(b.taskState)
+        });
+    });
+    const latestOutput = formatLatestOutput(arr(snap.tailLines));
+    const obj = str(mission.objective);
+    const objective = obj && obj.length > 100 ? obj.slice(0, 97) + '...' : obj;
+    return compact({
+        watchId: str(spec.watchId),
+        objective,
+        taskState: str(snap.taskState) ?? 'unknown',
+        exitCode: num(snap.exitCode),
+        stage: str(snap.stage),
+        summary: str(snap.summary),
+        latestOutput,
+        lifecycle: str(r.lifecycle),
+        health: str(r.health),
+        degradedReason: str(snap.degradedReason),
+        terminalAt: num(snap.terminalAt) !== undefined ? new Date(num(snap.terminalAt)).toISOString() : undefined,
+        lastObservedAt: num(snap.lastObservedAtMs) !== undefined ? new Date(num(snap.lastObservedAtMs)).toISOString() : undefined,
+        episodes: openEpisodes.length > 0 ? openEpisodes : undefined,
+        controlRevision: num(spec.controlRevision)
+    });
+}
+function projectControl(v) {
+    const r = rec(v);
+    return compact({
+        watchId: str(r.watchId),
+        lifecycle: str(r.lifecycle),
+        controlRevision: num(r.controlRevision)
+    });
+}
+export async function runToolAction(rt, params, actor) {
+    switch (params.action) {
+        case 'register': {
+            if (!params.requestId || !params.candidate) {
+                throw Object.assign(new Error('register requires requestId and candidate'), { code: 'INVALID_SPEC' });
+            }
+            // Finalize on demand before transport=relay registration (mid-session bind scenario)
+            if (params.candidate?.policy?.transport === 'relay') {
+                await rt.ensureRelayReady();
+            }
+            const spec = await rt.service.register(params.requestId, params.candidate, actor);
+            const isRelay = spec.policy.transport === 'relay';
+            return {
+                watchId: spec.watchId,
+                controlRevision: spec.controlRevision,
+                monitoringActive: true,
+                transport: isRelay ? 'relay' : 'local-display',
+                note: isRelay
+                    ? 'Watch active (relay wake enabled). Do NOT poll with write_stdin.'
+                    : 'Watch active (local-display). Do NOT poll with write_stdin.'
+            };
+        }
+        case 'list': {
+            // Owner decision 2026-09-21: in-session exec->watch loops accumulate many closed/failed terminal rows; echoing them all
+            // just burns model context (33 of 35 watches were converged history). By default only active (active/paused)
+            // watches + a terminalCount summary are returned; the model sees the full history only with explicit includeClosed=true.
+            const result = await rt.service.list(undefined, 50, actor, params.includeClosed ? undefined : ACTIVE_LIFECYCLES);
+            return projectList(result);
+        }
+        case 'watch-file': {
+            // Agent-declared file evidence source (universal monitor mode, decision-delta 2026-09-21):
+            // the agent pins an exact path (log_path from an exec result, a build artifact, a report file);
+            // the declarative pattern is the only content terminal-state evidence; growth means progress; silence is a stuck signal.
+            // Replaces the removed unified-exec adapter: no external-library naming heuristics, no runId namespace collisions.
+            if (!params.requestId || typeof params.path !== 'string' || params.path.trim() === '') {
+                throw Object.assign(new Error('watch-file requires requestId and path (absolute file path, e.g. the log_path from an exec_command result)'), { code: 'INVALID_SPEC' });
+            }
+            for (const [p, name] of [[params.okPattern, 'okPattern'], [params.failPattern, 'failPattern']]) {
+                if (p !== undefined) {
+                    try {
+                        new RegExp(p);
+                    }
+                    catch (e) {
+                        throw Object.assign(new Error(`${name} is not a valid RegExp: ${e instanceof Error ? e.message : String(e)}`), { code: 'INVALID_SPEC' });
+                    }
+                }
+            }
+            // Relative paths resolve against the declaring session's cwd (injected by the extension layer)
+            const filePath = pathMod.isAbsolute(params.path)
+                ? params.path
+                : (typeof params.cwd === 'string' && params.cwd !== '' ? pathMod.resolve(params.cwd, params.path) : pathMod.resolve(params.path));
+            const runId = fileRunId(filePath, { okPattern: params.okPattern, failPattern: params.failPattern });
+            // Dedup: an active watch with the same path + same pattern is returned directly (idempotent; keeps terminal history from crowding out the limit window)
+            const existing = await rt.service.list(undefined, 50, actor, ACTIVE_LIFECYCLES);
+            const prior = existing
+                .items?.find(w => w.target?.runId === runId && (w.lifecycle === 'active' || w.lifecycle === 'paused'));
+            if (prior?.watchId) {
+                return {
+                    watchId: prior.watchId,
+                    runId,
+                    controlRevision: prior.controlRevision ?? 1,
+                    transport: rt.negotiation.transport === 'relay' ? 'relay' : 'local-display',
+                    note: 'Already watching this file — progress via watcher inspect/check.'
+                };
+            }
+            const isRelay = rt.negotiation.transport === 'relay';
+            const candidate = {
+                mode: 'embedded',
+                target: {
+                    kind: 'run', sourceId: 'agent-file', taskId: 'file', runId, attemptId: 'attempt-1',
+                    file: {
+                        path: filePath,
+                        ...(params.okPattern !== undefined ? { okPattern: params.okPattern } : {}),
+                        ...(params.failPattern !== undefined ? { failPattern: params.failPattern } : {})
+                    }
+                },
+                mission: {
+                    objective: typeof params.objective === 'string' && params.objective
+                        ? params.objective
+                        : `file watch: ${pathMod.basename(filePath)}`,
+                    scope: `tail declared file ${filePath}; read-only`,
+                    checkpointId: 'file-watch',
+                    requiredArtifacts: [], requiresChecks: false, businessAcceptance: 'not_required',
+                    ...(typeof params.deadlineAt === 'string' ? { deadlineAt: params.deadlineAt } : {})
+                },
+                policy: {
+                    transport: isRelay ? 'relay' : 'local-display',
+                    semanticMode: params.semanticMode === 'active' || params.semanticMode === 'shadow' ? params.semanticMode : 'off',
+                    notificationOwner: 'watcher',
+                    requestKinds: [],
+                    maxRequestsPerEpisode: 1,
+                    episodeCooldownMs: 60000,
+                    attentionTtlMs: DEFAULT_ATTENTION_TTL_MS
+                },
+                limits: {
+                    // Local stat+read is cheap: fast sampling while active, backoff while quiet (same band as the old exec watch)
+                    pollMinMs: 1000, pollMaxMs: 5000,
+                    maxSilenceMs: typeof params.maxSilenceMs === 'number' ? params.maxSilenceMs : 600000,
+                    maxProbesPerEpisode: 2, maxJudgeRequestsPerDay: 10,
+                    // Round to the hour: the candidate digest stays stable when the same requestId is replayed (idempotent)
+                    expiresAt: new Date(Math.ceil(Date.now() / 3600_000) * 3600_000 + 12 * 3600_000).toISOString()
+                }
+            };
+            const spec = await rt.service.register(params.requestId, candidate, actor);
+            const relay = isRelay && spec.policy.transport === 'relay';
+            return {
+                watchId: spec.watchId,
+                runId,
+                path: filePath,
+                controlRevision: spec.controlRevision,
+                transport: relay ? 'relay' : 'local-display',
+                note: relay
+                    ? 'Watching file via relay wake. Call watcher inspect/check anytime.'
+                    : 'Watching file. Call watcher inspect/check anytime.'
+            };
+        }
+        case 'watch-check': {
+            // Bounded check command declared by the agent (decision-delta 2026-09-21): covers scenarios with no local artifact
+            // (CI build, cloud readiness, remote state). The watcher runs cmd periodically and maps results to facts via the declarative verdict mapping;
+            // a non-zero exit code is three-way ambiguous (failed/pending/broken), so the agent declares the mapping and the watcher does not guess.
+            if (!params.requestId || typeof params.cmd !== 'string' || params.cmd.trim() === '') {
+                throw Object.assign(new Error('watch-check requires requestId and cmd'), { code: 'INVALID_SPEC' });
+            }
+            if (params.cmd.length > 2000) {
+                throw Object.assign(new Error('cmd too long (max 2000 chars); put longer logic in a script file and check it'), { code: 'INVALID_SPEC' });
+            }
+            const patterns = [
+                [params.okPattern, 'okPattern'],
+                [params.failPattern, 'failPattern']
+            ];
+            for (const [p, name] of patterns) {
+                if (p !== undefined) {
+                    try {
+                        new RegExp(p);
+                    }
+                    catch (e) {
+                        throw Object.assign(new Error(`${name} is not a valid RegExp: ${e instanceof Error ? e.message : String(e)}`), { code: 'INVALID_SPEC' });
+                    }
+                }
+            }
+            const intervalMs = Math.min(Math.max(Math.trunc(params.intervalMs ?? 30_000), 1_000), 600_000);
+            const timeoutMs = Math.min(Math.max(Math.trunc(params.timeoutMs ?? 10_000), 1_000), 30_000);
+            const cmd = params.cmd;
+            const runId = checkRunId(cmd, { okPattern: params.okPattern, failPattern: params.failPattern, failCodes: params.failCodes });
+            // Dedup: an active watch with the same command + same verdict mapping is returned directly (idempotent)
+            const existing = await rt.service.list(undefined, 50, actor, ACTIVE_LIFECYCLES);
+            const prior = existing
+                .items?.find(w => w.target?.runId === runId && (w.lifecycle === 'active' || w.lifecycle === 'paused'));
+            if (prior?.watchId) {
+                return {
+                    watchId: prior.watchId,
+                    runId,
+                    controlRevision: prior.controlRevision ?? 1,
+                    transport: rt.negotiation.transport === 'relay' ? 'relay' : 'local-display',
+                    note: 'Already watching this check command — progress via watcher inspect/check.'
+                };
+            }
+            const isRelay = rt.negotiation.transport === 'relay';
+            const candidate = {
+                mode: 'embedded',
+                target: {
+                    kind: 'run', sourceId: 'agent-check', taskId: 'check', runId, attemptId: 'attempt-1',
+                    check: {
+                        cmd,
+                        ...(typeof params.cwd === 'string' && params.cwd !== '' ? { cwd: params.cwd } : {}),
+                        timeoutMs,
+                        ...(params.okPattern !== undefined ? { okPattern: params.okPattern } : {}),
+                        ...(params.failPattern !== undefined ? { failPattern: params.failPattern } : {}),
+                        ...(Array.isArray(params.failCodes) ? { failCodes: params.failCodes } : {})
+                    }
+                },
+                mission: {
+                    objective: typeof params.objective === 'string' && params.objective ? params.objective : `agent check: ${cmd.slice(0, 100)}`,
+                    scope: 'run agent-declared bounded check command; read-only intent',
+                    checkpointId: 'check-watch',
+                    requiredArtifacts: [], requiresChecks: false, businessAcceptance: 'not_required',
+                    ...(typeof params.deadlineAt === 'string' ? { deadlineAt: params.deadlineAt } : {})
+                },
+                policy: {
+                    transport: isRelay ? 'relay' : 'local-display',
+                    semanticMode: params.semanticMode === 'active' || params.semanticMode === 'shadow' ? params.semanticMode : 'off',
+                    notificationOwner: 'watcher',
+                    requestKinds: [],
+                    maxRequestsPerEpisode: 1,
+                    episodeCooldownMs: 60_000,
+                    attentionTtlMs: DEFAULT_ATTENTION_TTL_MS
+                },
+                limits: {
+                    // Fixed cadence (pollMin=pollMax=interval): no new information is not a backoff signal, so the cadence stays predictable
+                    pollMinMs: intervalMs, pollMaxMs: intervalMs,
+                    // Long pending is the normal shape of a readiness check: default silence is 30min (overridable)
+                    maxSilenceMs: typeof params.maxSilenceMs === 'number' ? params.maxSilenceMs : 1_800_000,
+                    maxProbesPerEpisode: 2, maxJudgeRequestsPerDay: 10,
+                    expiresAt: new Date(Math.ceil(Date.now() / 3600_000) * 3600_000 + 12 * 3600_000).toISOString()
+                }
+            };
+            const spec = await rt.service.register(params.requestId, candidate, actor);
+            const relay = isRelay && spec.policy.transport === 'relay';
+            return {
+                watchId: spec.watchId,
+                runId,
+                controlRevision: spec.controlRevision,
+                transport: relay ? 'relay' : 'local-display',
+                intervalMs,
+                timeoutMs,
+                note: relay
+                    ? 'Watching check command via relay wake. Call watcher inspect/check anytime.'
+                    : 'Watching check command. Call watcher inspect/check anytime.'
+            };
+        }
+        case 'inspect': {
+            if (!params.watchId)
+                throw Object.assign(new Error('inspect requires watchId'), { code: 'INVALID_SPEC' });
+            return projectInspect(await rt.service.inspect(params.watchId, actor));
+        }
+        case 'check': {
+            if (!params.requestId || !params.watchId || typeof params.expectedControlRevision !== 'number') {
+                throw Object.assign(new Error('check requires requestId, watchId, expectedControlRevision'), { code: 'INVALID_SPEC' });
+            }
+            const r = await rt.service.check(params.requestId, params.watchId, params.expectedControlRevision, actor);
+            const inspection = projectInspect(await rt.service.inspect(params.watchId, actor));
+            return {
+                inspectionId: r.inspectionId,
+                ...inspection,
+                note: 'Live progress refreshed from source.'
+            };
+        }
+        case 'pause':
+        case 'close': {
+            if (!params.requestId || !params.watchId || typeof params.expectedControlRevision !== 'number') {
+                throw Object.assign(new Error(`${params.action} requires requestId, watchId, expectedControlRevision, reason`), { code: 'INVALID_SPEC' });
+            }
+            return projectControl(await rt.service.control(params.requestId, params.watchId, params.expectedControlRevision, params.action, params.reason ?? 'via watcher tool', actor));
+        }
+        case 'ack': {
+            // No relay delivery: do not fabricate a receipt out of thin air (design 11.7)
+            throw Object.assign(new Error('ack requires a relay consumer delivery (deliveryRef); relay managed path not negotiated — use local owner panel instead'), { code: 'NO_DELIVERY' });
+        }
+        case 'update': {
+            throw Object.assign(new Error('update is owner-scoped and not yet implemented (V1)'), { code: 'INVALID_SPEC' });
+        }
+        default:
+            throw Object.assign(new Error(`unknown action ${String(params.action)}`), { code: 'INVALID_SPEC' });
+    }
+}

package/dist/engine/widget.d.ts

@@ -0,0 +1,29 @@
+/**
+ * TUI status bar widget rendering (design 11 §33: ordinary progress updates the same widget and produces no long transcript;
+ * design 08 §35: normal status updates go to the widget and not into the LLM context).
+ *
+ * Parallels pi-scheduler's `[scheduler] N scheduled · ...`, but the semantics are fact-driven:
+ * - watch counts (active / paused)
+ * - unresolved episode count (open / snoozed / acknowledged)
+ * - nearest deadline (relative time; add [!] when overdue)
+ * - unhealthy watch (degraded/blind) count [!]
+ * - number of attention items awaiting host response (attention events whose episode is still open/snoozed)
+ *
+ * Pure function: the string[] overload leaves coloring to Pi defaults; returns [] (hides the widget) when there are no watches.
+ */
+export interface WidgetWatch {
+    lifecycle: string;
+    health: string;
+    deadlineAt?: string | null;
+}
+export interface WatcherWidgetInput {
+    watches: WidgetWatch[];
+    /** Total unresolved episodes (state in open/snoozed/acknowledged) */
+    unresolvedEpisodes: number;
+    /** Attention outbox events whose episode is still open/snoozed (awaiting host response) */
+    pendingAttentions: number;
+    now: number;
+}
+/** Relative time: before now -> "in 12m"; after -> "12m overdue"; <1m -> "now"/"just now". */
+export declare function formatRelative(ms: number): string;
+export declare function renderWatcherWidget(input: WatcherWidgetInput): string[];

package/dist/engine/widget.js

@@ -0,0 +1,52 @@
+/**
+ * TUI status bar widget rendering (design 11 §33: ordinary progress updates the same widget and produces no long transcript;
+ * design 08 §35: normal status updates go to the widget and not into the LLM context).
+ *
+ * Parallels pi-scheduler's `[scheduler] N scheduled · ...`, but the semantics are fact-driven:
+ * - watch counts (active / paused)
+ * - unresolved episode count (open / snoozed / acknowledged)
+ * - nearest deadline (relative time; add [!] when overdue)
+ * - unhealthy watch (degraded/blind) count [!]
+ * - number of attention items awaiting host response (attention events whose episode is still open/snoozed)
+ *
+ * Pure function: the string[] overload leaves coloring to Pi defaults; returns [] (hides the widget) when there are no watches.
+ */
+/** Relative time: before now -> "in 12m"; after -> "12m overdue"; <1m -> "now"/"just now". */
+export function formatRelative(ms) {
+    const abs = Math.abs(ms);
+    const text = abs < 60_000 ? '<1m'
+        : abs < 3_600_000 ? `${Math.round(abs / 60_000)}m`
+            : abs < 86_400_000 ? `${Math.round(abs / 3_600_000)}h`
+                : `${Math.round(abs / 86_400_000)}d`;
+    return ms > 0 ? `in ${text}` : `${text} overdue`;
+}
+export function renderWatcherWidget(input) {
+    const watches = input.watches.filter(w => w.lifecycle !== 'closed' && w.lifecycle !== 'expired');
+    if (watches.length === 0)
+        return [];
+    const active = watches.filter(w => w.lifecycle === 'active');
+    const paused = watches.filter(w => w.lifecycle === 'paused');
+    const unhealthy = watches.filter(w => w.health === 'degraded' || w.health === 'blind');
+    const parts = [];
+    parts.push(`${active.length} watch${active.length === 1 ? '' : 'es'}`);
+    if (paused.length > 0)
+        parts.push(`${paused.length} paused`);
+    if (input.unresolvedEpisodes > 0) {
+        parts.push(`${input.unresolvedEpisodes} open ep${input.unresolvedEpisodes === 1 ? '' : 's'}`);
+    }
+    // Nearest business deadline (taken only from active watches; paused ones are not nagged). Wording uses due (the moment the task should be done)
+    // rather than deadline, to distinguish it from timing concepts like watch expiry and silence budget
+    const deadlines = active
+        .map(w => (w.deadlineAt ? Date.parse(w.deadlineAt) : NaN))
+        .filter(Number.isFinite);
+    if (deadlines.length > 0) {
+        const nearest = Math.min(...deadlines);
+        const rel = formatRelative(nearest - input.now);
+        parts.push(nearest <= input.now ? `[!] due ${rel}` : `due ${rel}`);
+    }
+    if (unhealthy.length > 0)
+        parts.push(`[!] ${unhealthy.length} degraded`);
+    if (input.pendingAttentions > 0)
+        parts.push(`${input.pendingAttentions} attn pending`);
+    return [`[watcher] ${parts.join(' · ')}`];
+}

package/dist/ipc/client.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared runtime IPC client (attached session side).
+ * Single in-flight queue + line-delimited JSON frames; a disconnect/timeout marks the backend as lost,
+ * and the upper layer triggers failover (retry the lock to promote to primary, or attach to a new primary).
+ */
+import type { IpcRequest, IpcResponse } from './server.js';
+export interface RuntimeIpcClientOptions {
+    connectTimeoutMs?: number;
+    requestTimeoutMs?: number;
+}
+export declare class RuntimeIpcClient {
+    private readonly socket;
+    private readonly requestTimeoutMs;
+    private buf;
+    private dead;
+    private queue;
+    private pending;
+    private constructor();
+    static connect(socketPath: string, options?: RuntimeIpcClientOptions): Promise<RuntimeIpcClient>;
+    get isDead(): boolean;
+    request(req: IpcRequest): Promise<IpcResponse>;
+    close(): void;
+    private onData;
+    private failPending;
+    private markDead;
+}

package/dist/ipc/client.js

@@ -0,0 +1,106 @@
+/**
+ * Shared runtime IPC client (attached session side).
+ * Single in-flight queue + line-delimited JSON frames; a disconnect/timeout marks the backend as lost,
+ * and the upper layer triggers failover (retry the lock to promote to primary, or attach to a new primary).
+ */
+import * as net from 'node:net';
+import { WatcherError } from '../util/result.js';
+export class RuntimeIpcClient {
+    socket;
+    requestTimeoutMs;
+    buf = '';
+    dead = false;
+    queue = Promise.resolve();
+    pending = null;
+    constructor(socket, requestTimeoutMs) {
+        this.socket = socket;
+        this.requestTimeoutMs = requestTimeoutMs;
+        socket.setEncoding('utf8');
+        socket.on('data', (d) => this.onData(d));
+        socket.on('close', () => this.markDead());
+        socket.on('error', () => this.markDead());
+    }
+    static async connect(socketPath, options = {}) {
+        const timeoutMs = options.connectTimeoutMs ?? 1500;
+        const socket = await new Promise((resolve, reject) => {
+            const s = net.connect(socketPath);
+            const timer = setTimeout(() => {
+                s.destroy();
+                reject(new WatcherError('ROOT_LOCK_HELD', `watcher shared runtime socket connect timeout: ${socketPath}`));
+            }, timeoutMs);
+            s.once('connect', () => { clearTimeout(timer); resolve(s); });
+            s.once('error', e => {
+                clearTimeout(timer);
+                reject(new WatcherError('ROOT_LOCK_HELD', `watcher shared runtime socket unreachable (${e instanceof Error ? e.message : String(e)}): ${socketPath}`));
+            });
+        });
+        return new RuntimeIpcClient(socket, options.requestTimeoutMs ?? 20000);
+    }
+    get isDead() { return this.dead; }
+    request(req) {
+        const run = async () => {
+            if (this.dead) {
+                throw new WatcherError('STORE_UNAVAILABLE', 'watcher shared runtime connection lost');
+            }
+            return await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    this.failPending(new WatcherError('STORE_UNAVAILABLE', 'watcher shared runtime request timeout'));
+                }, this.requestTimeoutMs);
+                this.pending = { resolve, reject, timer };
+                this.socket.write(JSON.stringify(req) + '\n', err => {
+                    if (err)
+                        this.failPending(new WatcherError('STORE_UNAVAILABLE', `watcher shared runtime write failed: ${err.message}`));
+                });
+            });
+        };
+        const p = this.queue.then(run, run);
+        this.queue = p.catch(() => undefined);
+        return p;
+    }
+    close() {
+        this.markDead();
+        this.socket.destroy();
+    }
+    onData(d) {
+        this.buf += d;
+        let idx;
+        while ((idx = this.buf.indexOf('\n')) >= 0) {
+            const line = this.buf.slice(0, idx);
+            this.buf = this.buf.slice(idx + 1);
+            if (!line.trim())
+                continue;
+            const p = this.pending;
+            this.pending = null;
+            if (!p)
+                continue;
+            clearTimeout(p.timer);
+            try {
+                p.resolve(JSON.parse(line));
+            }
+            catch (e) {
+                p.reject(new WatcherError('STORE_UNAVAILABLE', `watcher shared runtime malformed response: ${e instanceof Error ? e.message : String(e)}`));
+            }
+        }
+    }
+    failPending(e) {
+        const p = this.pending;
+        this.pending = null;
+        this.markDead();
+        if (p) {
+            clearTimeout(p.timer);
+            p.reject(e);
+        }
+    }
+    markDead() {
+        if (this.dead)
+            return;
+        this.dead = true;
+        const p = this.pending;
+        this.pending = null;
+        if (p) {
+            clearTimeout(p.timer);
+            p.reject(new WatcherError('STORE_UNAVAILABLE', 'watcher shared runtime connection lost'));
+        }
+        this.socket.destroy();
+    }
+}

package/dist/ipc/server.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Shared runtime IPC server (primary side).
+ * Multiple pi sessions on the same project root share one embedded runtime: the lock-holding session (primary) serves
+ * attached sessions' tool/panel/widget requests on this unix socket. Protocol: line-delimited JSON.
+ *
+ * Invariant (design 7.2): the whole project still has a single store writer (the only opener under epoch fencing).
+ * Attached sessions never open the DB -- all mutations are serialized through the primary.
+ */
+/** JSON wire format of ActorContext (permitted: Set -> string[]). */
+export interface WireActor {
+    actorId: string;
+    owner: Record<string, unknown>;
+    profileRevision: number;
+    permitted: string[];
+}
+export type IpcRequest = {
+    op: 'tool';
+    params: Record<string, unknown>;
+    actor: WireActor;
+} | {
+    op: 'panel';
+    actor: WireActor;
+} | {
+    op: 'ack';
+    episodeId: string;
+    action: string;
+    note: string;
+    until?: string;
+    requestId: string;
+    actor: WireActor;
+} | {
+    op: 'widget';
+    lastNotifySeq?: number;
+    ownerSession?: string;
+};
+/** Same shape as ServiceResult: the result envelope across the wire. */
+export interface IpcOk {
+    ok: true;
+    requestId?: string;
+    value: unknown;
+}
+export interface IpcErr {
+    ok: false;
+    requestId?: string;
+    error: {
+        code: string;
+        message: string;
+    };
+}
+export type IpcResponse = IpcOk | IpcErr;
+export interface IpcHandlers {
+    tool(params: Record<string, unknown>, actor: WireActor): Promise<IpcResponse>;
+    panel(actor: WireActor): Promise<IpcResponse>;
+    ack(req: {
+        episodeId: string;
+        action: string;
+        note: string;
+        until?: string;
+        requestId: string;
+    }, actor: WireActor): Promise<IpcResponse>;
+    /** Widget snapshot + incremental attention notices (notices after lastNotifySeq, optionally filtered by ownerSession) */
+    widget(lastNotifySeq?: number, ownerSession?: string): IpcResponse;
+}
+export declare function runtimeSocketPath(rootDir: string): string;
+export declare class RuntimeIpcServer {
+    private readonly socketPath;
+    private readonly handlers;
+    private server;
+    constructor(socketPath: string, handlers: IpcHandlers);
+    /**
+     * Call only after holding the root flock: any existing socket file is then a leftover from a crashed primary,
+     * so unlink is safe (a live primary's socket cannot coexist with us -- flock is exclusive).
+     */
+    start(): Promise<void>;
+    close(): Promise<void>;
+    private handleConn;
+    private dispatch;
+}