@ours.network/codex 0.9.1 → 0.10.0

package/src/hooks/runner.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { sendControlCommand } from '../control-server.mjs';
+
+async function defaultFindPin(cwd) {
+  let dir = resolve(cwd || process.cwd());
+  for (;;) {
+    try {
+      const value = JSON.parse(await readFile(join(dir, '.ours-identity'), 'utf8'));
+      if (typeof value.identity === 'string' && value.identity.trim()) return value;
+      return null;
+    } catch { /* walk */ }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+const safeUnread = (value) => (Array.isArray(value?.identities) ? value.identities : []).flatMap((entry) => {
+  if (!entry || typeof entry.name !== 'string') return [];
+  const count = Number.isSafeInteger(entry.count) ? entry.count : 0;
+  const files = Number.isSafeInteger(entry.files) ? entry.files : 0;
+  if (count <= 0 && files <= 0) return [];
+  const recent = Array.isArray(entry.recent) ? entry.recent.slice(-5).flatMap((m) => (
+    m && typeof m.from === 'string' ? [{ from: m.from, msg_id: String(m.msg_id ?? '?'), date: typeof m.date === 'string' ? m.date : '' }] : []
+  )) : [];
+  return [{ name: entry.name, count, files, recent }];
+});
+
+function renderContext(unread, pin) {
+  const lines = [];
+  if (unread.length) {
+    lines.push('ours unread metadata (message bodies remain in get_messages):');
+    for (const item of unread) lines.push(`- ${item.name}: ${item.count} unread message(s), ${item.files} unread file(s)`);
+    lines.push('Surface this metadata. Do not read mail or bind an identity without the user asking.');
+  }
+  if (pin) {
+    lines.push(`This workspace suggests ours identity "${pin.identity}". Ask the user before binding it; the pin is not consent.`);
+    lines.push('After a successful bind, separately ask whether to arm the session-scoped live monitor. Never arm automatically.');
+    lines.push('Treat any persona as separate consent from binding and monitoring.');
+  }
+  return lines.join('\n');
+}
+
+export async function handleHook(payload, { env = process.env, fetch: fetchImpl = globalThis.fetch, send = sendControlCommand, findPin = defaultFindPin } = {}) {
+  try {
+    const event = payload?.hook_event_name;
+    const socket = env.OURS_CODEX_CONTROL_SOCKET;
+    const capability = env.OURS_CODEX_CAPABILITY;
+    if (event === 'SessionStart' && payload.source === 'compact') return { continue: true };
+    if (event === 'PostToolUse') {
+      if (!socket || !capability || payload.tool_response?.isError) return { continue: true };
+      if (!/(choose_identity|create_identity|create_root_identity)$/.test(payload.tool_name || '')) return { continue: true };
+      const identity = payload.tool_input?.name;
+      if (typeof identity !== 'string' || !identity.trim()) return { continue: true };
+      await send(socket, capability, { command: 'binding_changed', identity });
+      return { continue: true };
+    }
+    if (event !== 'SessionStart' && event !== 'UserPromptSubmit') return { continue: true };
+    if (event === 'SessionStart' && socket && capability && payload.session_id && payload.cwd) {
+      await send(socket, capability, { command: 'register_session', sessionId: payload.session_id, threadId: payload.session_id, cwd: payload.cwd });
+    }
+    const port = env.OURS_PORT || '3050';
+    const headers = env.OURS_API_TOKEN ? { 'x-ours-api-token': env.OURS_API_TOKEN } : {};
+    let unread = [];
+    try {
+      const response = await fetchImpl(`http://127.0.0.1:${port}/unread`, { headers, signal: AbortSignal.timeout(1500) });
+      if (response.ok) unread = safeUnread(await response.json());
+    } catch { /* daemon diagnostics belong to launcher/proxy */ }
+    const pin = await findPin(payload.cwd || process.cwd());
+    const context = renderContext(unread, pin);
+    if (!context) return { continue: true };
+    return { continue: true, hookSpecificOutput: { hookEventName: event, additionalContext: context } };
+  } catch { return { continue: true }; }
+}
+
+async function main() {
+  let payload = {};
+  try { payload = JSON.parse(await readFile(0, 'utf8')); } catch { /* noop */ }
+  process.stdout.write(JSON.stringify(await handleHook(payload)));
+}
+
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) main();
+

package/src/launcher.mjs

@@ -0,0 +1,145 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { createServer } from 'node:net';
+import { chmod, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { once } from 'node:events';
+import { resolveDaemonProfile } from './profile.mjs';
+import { connectAppServer } from './app-server-client.mjs';
+import { AtomicStateStore, ControlServer } from './control-server.mjs';
+import { MonitorWatcher } from './watcher.mjs';
+
+export function validatePlatform(platform = process.platform) {
+  if (platform === 'win32') throw new Error('native Windows is not supported in ours-codex v1; run it inside WSL');
+}
+export const appServerArgs = (url, codexArgs = []) => [
+  ...(codexArgs.includes('--dangerously-bypass-hook-trust') ? ['--dangerously-bypass-hook-trust'] : []),
+  'app-server', '--listen', url,
+];
+export const remoteTuiArgs = (url, codexArgs) => ['--remote', url, ...codexArgs];
+
+export function launcherEnvironment(env, profile, control) {
+  const out = {
+    ...env,
+    OURS_PORT: String(profile.port),
+    OURS_CONFIG: profile.configPath,
+    OURS_AUTOSTART: '0',
+    OURS_CODEX_CONTROL_SOCKET: control.socketPath,
+    OURS_CODEX_CAPABILITY: control.capability,
+    OURS_CODEX_LIVE: '1',
+  };
+  if (profile.token) out.OURS_API_TOKEN = profile.token;
+  else delete out.OURS_API_TOKEN;
+  return out;
+}
+
+export function liveProcessEnvironments(env, profile, control) {
+  const live = launcherEnvironment(env, profile, control);
+  return { appServer: live, tui: live };
+}
+
+export function sessionRegistrationFromNotification(message, cwd) {
+  const threadId = message?.method === 'thread/started' ? message.params?.thread?.id
+    : message?.method === 'turn/started' ? (message.params?.threadId || message.params?.thread?.id)
+      : null;
+  return typeof threadId === 'string' && threadId
+    ? { command: 'register_session', sessionId: threadId, threadId, cwd }
+    : null;
+}
+
+async function freePort() {
+  const server = createServer();
+  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); });
+  const port = server.address().port;
+  await new Promise((resolve) => server.close(resolve));
+  return port;
+}
+
+async function waitReady(url, fetchImpl, child) {
+  for (let attempt = 0; attempt < 80; attempt += 1) {
+    if (child.exitCode != null) throw new Error(`Codex App Server exited early (${child.exitCode})`);
+    try { if ((await fetchImpl(`${url.replace(/^ws/, 'http')}/readyz`)).ok) return; } catch { /* startup */ }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  throw new Error('Codex App Server did not become ready');
+}
+
+function waitExit(child) {
+  if (child.exitCode != null) return Promise.resolve({ code: child.exitCode, signal: child.signalCode });
+  return once(child, 'exit').then(([code, signal]) => ({ code, signal }));
+}
+
+export async function runLauncher({
+  argv = process.argv.slice(2), env = process.env, platform = process.platform,
+  spawn = nodeSpawn, fetch: fetchImpl = globalThis.fetch,
+  profileResolver = resolveDaemonProfile, connect = connectAppServer,
+} = {}) {
+  validatePlatform(platform);
+  const profile = await profileResolver({ argv, env, fetch: fetchImpl });
+  const runtimeBase = env.XDG_RUNTIME_DIR || tmpdir();
+  const runtimeDir = await mkdtemp(join(runtimeBase, 'ours-codex-'));
+  await chmod(runtimeDir, 0o700);
+  const socketPath = join(runtimeDir, 'control.sock');
+  const capability = randomBytes(32).toString('hex');
+  const url = `ws://127.0.0.1:${await freePort()}`;
+  const processEnvs = liveProcessEnvironments(env, profile, { socketPath, capability });
+  let appServer;
+  let tui;
+  let client;
+  let control;
+  let watcher;
+  const cleanup = async () => {
+    watcher?.stop();
+    await control?.close().catch(() => {});
+    client?.close();
+    if (tui && tui.exitCode == null) tui.kill('SIGTERM');
+    if (appServer && appServer.exitCode == null) appServer.kill('SIGTERM');
+    await rm(runtimeDir, { recursive: true, force: true });
+  };
+  const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+  const handlers = new Map();
+  try {
+    appServer = spawn('codex', appServerArgs(url, profile.codexArgs), { env: processEnvs.appServer, stdio: ['ignore', 'ignore', 'inherit'] });
+    appServer.once('error', () => {});
+    await waitReady(url, fetchImpl, appServer);
+    client = await connect(url, { timeoutMs: 30_000 });
+    client.onServerRequest((message) => {
+      if (message.method.includes('requestApproval')) return { decision: 'decline' };
+      throw new Error(`ours monitor cannot answer ${message.method}`);
+    });
+    watcher = new MonitorWatcher({
+      baseUrl: profile.baseUrl, token: profile.token, fetch: fetchImpl, appServer: client,
+      stateStore: new AtomicStateStore(join(runtimeDir, 'cursor.json')),
+    });
+    control = new ControlServer({
+      socketPath, capability, stateStore: new AtomicStateStore(join(runtimeDir, 'state.json')),
+      onEffects: async (effects, state) => {
+        for (const effect of effects) {
+          if (effect.type === 'unsubscribe') watcher.stop();
+          if (effect.type === 'subscribe') {
+            if (!state.threadId) throw new Error('Codex session has not registered its thread yet');
+            void watcher.start({ identity: effect.identity, threadId: state.threadId, cursor: state.cursor }).catch(() => {});
+          }
+        }
+      },
+    });
+    await control.start();
+    client.onNotification((message) => {
+      const registration = sessionRegistrationFromNotification(message, profile.cwd || process.cwd());
+      if (registration) void control.apply(registration);
+    });
+    tui = spawn('codex', remoteTuiArgs(url, profile.codexArgs), { env: processEnvs.tui, stdio: 'inherit' });
+    for (const signal of signals) {
+      const handler = () => { if (tui?.exitCode == null) tui.kill(signal); };
+      handlers.set(signal, handler); process.on(signal, handler);
+    }
+    const outcome = await waitExit(tui);
+    return outcome.signal ? 128 : (outcome.code ?? 0);
+  } catch (error) {
+    throw new Error(`${error.message}\nStandard mode remains available with: codex`);
+  } finally {
+    for (const [signal, handler] of handlers) process.off(signal, handler);
+    await cleanup();
+  }
+}

package/src/monitor-mcp.mjs

@@ -0,0 +1,133 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { z } from 'zod';
+import { sendControlCommand } from './control-server.mjs';
+
+const require = createRequire(import.meta.url);
+export const monitorToolNames = ['arm_monitor', 'foreground_monitor', 'disarm_monitor', 'monitor_status'];
+const content = (text, isError = false) => ({ content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}) });
+
+const foregroundOffer = (identity) =>
+  'IMPORTANT: Before offering the fallback, tell the user exactly: ' +
+  '"This standard `codex` session only supports a blocking foreground monitor. ' +
+  'For background monitoring, restart the session with `ours-codex` instead; it adds ' +
+  'the App Server integration needed for session-scoped background wake." ' +
+  'A blocking foreground monitor is available here, but while it waits this Codex session ' +
+  'cannot accept another prompt (press Escape to stop it). ' +
+  `Ask the user: "Do you want to arm the foreground blocking monitor here?" ` +
+  `Only after an explicit yes, call get_messages once to drain existing unread mail, then ` +
+  `call foreground_monitor({ identity: ${JSON.stringify(identity)} }).`;
+
+function foregroundWatchProcess(identity) {
+  try {
+    const cliPath = require.resolve('@ours.network/mcp/dist/cli.js');
+    return { command: process.execPath, args: [cliPath, 'watch', identity] };
+  } catch {
+    return { command: 'ours-mcp', args: ['watch', identity] };
+  }
+}
+
+export async function handleMonitorCommand(command, args = {}, { env = process.env, send = sendControlCommand } = {}) {
+  const socket = env.OURS_CODEX_CONTROL_SOCKET;
+  const capability = env.OURS_CODEX_CAPABILITY;
+  if (!socket || !capability) {
+    if (command === 'arm') return { text: foregroundOffer(args.identity), mode: 'foreground-offer' };
+    if (command === 'disarm') return { text: 'No background monitor is armed. A blocking foreground monitor stops when its tool call is interrupted.' };
+    return { text: 'Background mail monitoring is unavailable in this standard Codex session. Use `ours-codex` for background wake, or explicitly arm the blocking foreground monitor for the bound identity.' };
+  }
+  const wire = command === 'arm' ? { command: 'arm', identity: args.identity }
+    : command === 'disarm' ? { command: 'disarm' } : { command: 'status' };
+  const response = await send(socket, capability, wire);
+  const state = response.state;
+  if (command === 'arm') return { text: `Live ours monitor armed for "${state.armedIdentity}". It stops when this Codex CLI session exits.` };
+  if (command === 'disarm') return { text: 'Live ours monitor disarmed.' };
+  return { text: state.armedIdentity
+    ? `Live ours monitor is armed for "${state.armedIdentity}"${state.turnActive ? '; a turn is active' : ''}.`
+    : `Live ours monitor is available but not armed${state.boundIdentity ? `; current binding is "${state.boundIdentity}"` : '; bind an identity first'}.` };
+}
+
+export function waitForForegroundMail(identity, {
+  env = process.env,
+  spawnImpl = spawn,
+  signal,
+  commandFor = foregroundWatchProcess,
+} = {}) {
+  if (typeof identity !== 'string' || !identity.trim()) return Promise.reject(new Error('identity is required'));
+
+  return new Promise((resolve, reject) => {
+    const invocation = commandFor(identity);
+    const child = spawnImpl(invocation.command, invocation.args, {
+      env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+
+    const stop = () => {
+      if (!child.killed) child.kill('SIGTERM');
+    };
+    const finish = (fn, value) => {
+      if (settled) return;
+      settled = true;
+      signal?.removeEventListener('abort', onAbort);
+      stop();
+      fn(value);
+    };
+    const onAbort = () => finish(reject, new Error('foreground monitor stopped'));
+
+    if (signal?.aborted) return onAbort();
+    signal?.addEventListener('abort', onAbort, { once: true });
+    child.once('error', (error) => finish(reject, error));
+    child.stderr?.on('data', (chunk) => { stderr += String(chunk); });
+    child.stdout?.on('data', (chunk) => {
+      stdout += String(chunk);
+      const newline = stdout.indexOf('\n');
+      if (newline === -1) return;
+      const event = stdout.slice(0, newline).trim();
+      if (event) finish(resolve, event);
+    });
+    child.once('exit', (code, childSignal) => {
+      if (settled) return;
+      const detail = stderr.trim() || `exit ${code ?? childSignal ?? 'unknown'}`;
+      finish(reject, new Error(`ours-mcp watch stopped before mail arrived: ${detail}`));
+    });
+  });
+}
+
+export function createMonitorMcpServer(deps = {}) {
+  const server = new McpServer({ name: 'ours-monitor', version: '0.9.1' });
+  server.tool('arm_monitor', 'Arm session-scoped live mail wake for the currently bound ours identity. Call only after explicit user consent. If standard mode is reported, relay its ours-codex background-monitor recommendation to the user verbatim before offering the foreground fallback.', {
+    identity: z.string().min(1).describe('The already-bound ours identity to monitor.'),
+  }, async ({ identity }) => {
+    try { return content((await handleMonitorCommand('arm', { identity }, deps)).text); }
+    catch (error) { return content(`Could not arm live monitor: ${error.message}`, true); }
+  });
+  server.tool('foreground_monitor', 'Block this Codex turn until new mail arrives for the bound ours identity. Never call unless the user was first told that ours-codex provides background monitoring and then explicitly accepted this foreground fallback.', {
+    identity: z.string().min(1).describe('The already-bound ours identity to monitor.'),
+  }, async ({ identity }, extra) => {
+    try {
+      const event = await waitForForegroundMail(identity, { ...deps, signal: extra?.signal });
+      return content(`Foreground ours monitor received a body-free arrival event: ${event}\nCall get_messages now. After handling the mail, call foreground_monitor again without asking if monitoring should remain armed.`);
+    } catch (error) {
+      if (extra?.signal?.aborted) return content('Foreground ours monitor stopped. It is no longer armed.');
+      return content(`Foreground ours monitor failed: ${error.message}`, true);
+    }
+  });
+  server.tool('disarm_monitor', 'Stop this session’s live ours mail wake monitor.', {}, async () => {
+    try { return content((await handleMonitorCommand('disarm', {}, deps)).text); }
+    catch (error) { return content(`Could not disarm live monitor: ${error.message}`, true); }
+  });
+  server.tool('monitor_status', 'Report whether live ours mail wake is available and armed.', {}, async () => {
+    try { return content((await handleMonitorCommand('status', {}, deps)).text); }
+    catch (error) { return content(`Could not read monitor status: ${error.message}`, true); }
+  });
+  return server;
+}
+
+export async function runMonitorMcp() {
+  const server = createMonitorMcpServer();
+  await server.connect(new StdioServerTransport());
+}

package/src/monitor-state.mjs

@@ -0,0 +1,55 @@
+export function createMonitorState(overrides = {}) {
+  return {
+    sessionId: null, threadId: null, cwd: null,
+    boundIdentity: null, armedIdentity: null,
+    cursor: null, pendingWake: false, turnActive: false, lastError: null,
+    ...overrides,
+  };
+}
+
+const result = (state, effects = []) => ({ state, effects });
+
+export function registerSession(state, { sessionId, threadId, cwd }) {
+  return result({ ...state, sessionId, threadId, cwd });
+}
+
+export function bindingChanged(state, identity) {
+  const effects = [];
+  if (state.armedIdentity && state.armedIdentity !== identity) effects.push({ type: 'unsubscribe', identity: state.armedIdentity });
+  return result({ ...state, boundIdentity: identity, armedIdentity: state.armedIdentity === identity ? identity : null, cursor: state.armedIdentity === identity ? state.cursor : null, pendingWake: false }, effects);
+}
+
+export function arm(state, identity) {
+  if (!identity) throw new Error('cannot arm an empty identity');
+  if (state.boundIdentity && state.boundIdentity !== identity) throw new Error(`cannot arm ${identity}; current binding is ${state.boundIdentity}`);
+  if (state.armedIdentity === identity) return result(state);
+  // The arm tool itself is an explicit, identity-named consent boundary. Claiming an
+  // otherwise-unset binding here keeps live wake functional before plugin hooks have
+  // been reviewed; trusted PostToolUse hooks still synchronize later identity switches.
+  return result({ ...state, boundIdentity: identity, armedIdentity: identity, cursor: null, pendingWake: false, lastError: null }, [{ type: 'subscribe', identity }]);
+}
+
+export function disarm(state) {
+  const effects = state.armedIdentity ? [{ type: 'unsubscribe', identity: state.armedIdentity }] : [];
+  return result({ ...state, armedIdentity: null, cursor: null, pendingWake: false }, effects);
+}
+
+export function notificationArrived(state, cursor) {
+  if (!state.armedIdentity) return result({ ...state, cursor });
+  if (state.pendingWake) return result({ ...state, cursor });
+  if (state.turnActive) return result({ ...state, cursor, pendingWake: true });
+  return result({ ...state, cursor, pendingWake: true }, [{ type: 'startWakeTurn' }]);
+}
+
+export function turnStarted(state) {
+  return result({ ...state, turnActive: true, pendingWake: false });
+}
+
+export function turnCompleted(state) {
+  if (state.pendingWake && state.armedIdentity) return result({ ...state, turnActive: false }, [{ type: 'startWakeTurn' }]);
+  return result({ ...state, turnActive: false, pendingWake: false });
+}
+
+export function withError(state, error) {
+  return result({ ...state, lastError: String(error) });
+}

package/src/profile.mjs

@@ -0,0 +1,78 @@
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const DEFAULT_PORT = 3050;
+
+function validPort(value) {
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`ours: ${value} is not a valid TCP port`);
+  return port;
+}
+
+export function parseOursArgs(argv = []) {
+  const codexArgs = [];
+  let port;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--ours-port') {
+      if (argv[i + 1] == null) throw new Error('ours: --ours-port requires a value');
+      port = validPort(argv[++i]);
+    } else if (arg.startsWith('--ours-port=')) {
+      port = validPort(arg.slice('--ours-port='.length));
+    } else {
+      codexArgs.push(arg);
+    }
+  }
+  return { port, codexArgs };
+}
+
+async function readJson(path) {
+  try { return JSON.parse(await readFile(path, 'utf8')); } catch { return {}; }
+}
+
+async function readOwnerToken(stateDir) {
+  try { return (await readFile(join(stateDir, 'daemon-token'), 'utf8')).trim() || null; } catch { return null; }
+}
+
+export async function resolveDaemonProfile({ argv = [], env = process.env, readConfig, fetch: fetchImpl = globalThis.fetch } = {}) {
+  const parsed = parseOursArgs(argv);
+  const configPath = env.OURS_CONFIG || join(env.HOME || homedir(), '.ours', 'config.json');
+  const config = await (readConfig ? readConfig(configPath) : readJson(configPath));
+  let source = 'default';
+  let port = DEFAULT_PORT;
+  if (config?.port != null) { port = validPort(config.port); source = env.OURS_CONFIG ? 'OURS_CONFIG' : 'config'; }
+  if (env.OURS_PORT != null && env.OURS_PORT !== '') { port = validPort(env.OURS_PORT); source = 'OURS_PORT'; }
+  if (parsed.port != null) { port = parsed.port; source = '--ours-port'; }
+
+  const baseUrl = `http://127.0.0.1:${port}`;
+  let response;
+  try { response = await fetchImpl(`${baseUrl}/info`, { signal: AbortSignal.timeout(2000) }); }
+  catch (error) {
+    throw new Error(`ours daemon on port ${port} is not reachable; ours-codex never starts it. Start the selected daemon first. (${error?.message || error})`);
+  }
+  if (!response.ok) throw new Error(`ours daemon on port ${port} returned HTTP ${response.status}`);
+  const info = await response.json();
+  if (info?.name !== 'ours' || !Number.isInteger(info?.protocol) || info.protocol < 1 || typeof info?.stateDir !== 'string') {
+    throw new Error(`incompatible service on port ${port}; expected an ours daemon with notification protocol 1`);
+  }
+  const stateDir = resolve(info.stateDir);
+  const token = env.OURS_API_TOKEN?.trim() || config?.apiToken?.trim() || await readOwnerToken(stateDir);
+  const headers = token ? { 'x-ours-api-token': token } : {};
+  let capability;
+  try { capability = await fetchImpl(`${baseUrl}/identities`, { headers, signal: AbortSignal.timeout(2000) }); }
+  catch (error) { throw new Error(`ours daemon capability check failed: ${error?.message || error}`); }
+  if (capability.status === 401 || capability.status === 403) throw new Error(`ours daemon authentication failed on port ${port}; supply the matching OURS_API_TOKEN/config`);
+  if (!capability.ok) throw new Error(`selected daemon lacks the notification API (HTTP ${capability.status})`);
+  let unread;
+  try { unread = await fetchImpl(`${baseUrl}/unread`, { headers, signal: AbortSignal.timeout(2000) }); }
+  catch (error) { throw new Error(`ours daemon unread capability check failed: ${error?.message || error}`); }
+  if (unread.status === 401 || unread.status === 403) throw new Error(`ours daemon authentication failed on port ${port}; supply the matching OURS_API_TOKEN/config`);
+  if (!unread.ok) throw new Error(`selected daemon lacks the body-free unread API (HTTP ${unread.status}); install the testing daemon build and restart that daemon explicitly`);
+
+  return {
+    port, stateDir, token: token || null,
+    visibility: env.OURS_API_VISIBILITY || config?.apiVisibility || 'owner',
+    source, info, baseUrl, configPath, codexArgs: parsed.codexArgs,
+  };
+}

package/src/watcher.mjs

@@ -0,0 +1,110 @@
+export const WAKE_PROMPT = 'New ours mail is available for the identity already bound to this session. Use the ours skill and get_messages now, then handle the unread mail. Do not change identities or reveal message bodies outside the normal get_messages result.';
+
+export class MonitorWatcher {
+  constructor({ baseUrl, token = null, fetch: fetchImpl = globalThis.fetch, appServer, stateStore = { save: async () => {} }, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) }) {
+    this.baseUrl = baseUrl;
+    this.headers = token ? { 'x-ours-api-token': token } : {};
+    this.fetch = fetchImpl;
+    this.appServer = appServer;
+    this.stateStore = stateStore;
+    this.sleep = sleep;
+    this.authFailed = false;
+    this.running = false;
+    this.turnActive = false;
+    this.pending = false;
+    this.queued = false;
+    this.controller = null;
+    appServer?.onNotification?.((message) => {
+      if (message.method === 'turn/started') { this.turnActive = true; this.pending = false; }
+      if (message.method === 'turn/completed') {
+        this.turnActive = false;
+        if (this.pending && this.current) void this.#wake(this.current.threadId);
+      }
+    });
+  }
+
+  async #json(path, signal) {
+    const response = await this.fetch(`${this.baseUrl}${path}`, { headers: this.headers, signal });
+    if (response.status === 401 || response.status === 403) {
+      this.authFailed = true;
+      throw new Error('ours daemon authentication failed; monitor disarmed');
+    }
+    if (!response.ok) throw new Error(`ours daemon returned HTTP ${response.status}`);
+    return response.json();
+  }
+
+  async #wake(threadId) {
+    if (this.turnActive || this.pending) { this.queued = true; return; }
+    this.pending = true;
+    try {
+      const result = await this.appServer.startTurn(threadId, WAKE_PROMPT);
+      if (this.appServer.readThread && result?.turn?.id) void this.#trackCompletion(threadId, result.turn.id);
+      else this.pending = false;
+    }
+    catch (error) { this.pending = false; throw error; }
+  }
+
+  async #trackCompletion(threadId, turnId) {
+    try {
+      while (this.pending) {
+        const result = await this.appServer.readThread(threadId);
+        const turn = result?.thread?.turns?.find((item) => item.id === turnId);
+        if (turn && turn.status !== 'inProgress') break;
+        await this.sleep(250);
+      }
+    } catch { /* the next notification poll remains recoverable */ }
+    this.pending = false;
+    if (this.queued && this.current) {
+      this.queued = false;
+      void this.#wake(this.current.threadId);
+    }
+  }
+
+  async pollOnce({ identity, threadId, cursor }, signal) {
+    const since = cursor == null ? 'tip' : encodeURIComponent(cursor);
+    const data = await this.#json(`/identities/${encodeURIComponent(identity)}/notifications?since=${since}`, signal);
+    const next = { identity, threadId, cursor: String(data.cursor ?? cursor ?? '') };
+    await this.stateStore.save(next);
+    if (cursor == null) {
+      const unread = await this.#json('/unread', signal);
+      const entry = unread.identities?.find((item) => item.name === identity);
+      if (entry && (Number(entry.count) > 0 || Number(entry.files) > 0)) await this.#wake(threadId);
+    } else if (Array.isArray(data.events) && data.events.length > 0) {
+      await this.#wake(threadId);
+    }
+    return next;
+  }
+
+  start({ identity, threadId, cursor = null }) {
+    this.stop();
+    this.current = { identity, threadId, cursor };
+    this.running = true;
+    this.authFailed = false;
+    this.controller = new AbortController();
+    this.loopPromise = this.#loop(this.controller.signal);
+    return this.loopPromise;
+  }
+
+  async #loop(signal) {
+    let delay = 250;
+    while (this.running && !signal.aborted) {
+      try {
+        this.current = await this.pollOnce(this.current, signal);
+        delay = 250;
+      } catch (error) {
+        if (signal.aborted || !this.running) break;
+        if (this.authFailed) { this.running = false; throw error; }
+        await this.sleep(delay);
+        delay = Math.min(delay * 2, 10_000);
+      }
+    }
+  }
+
+  stop() {
+    this.running = false;
+    this.controller?.abort();
+    this.controller = null;
+    this.pending = false;
+    this.queued = false;
+  }
+}