@venturewild/workspace 0.1.1 → 0.1.2

package/server/src/config.mjs

@@ -8,6 +8,7 @@ import crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 
 import { loadAccount } from './account.mjs';
+import { loadOperatorToken } from './operator.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -74,6 +75,8 @@ export const ROLES = Object.freeze({
   PARTNER: 'partner',
   VIEWER: 'viewer',
   CLIENT: 'client',
+  // The consented support/operator channel (off by default — see operator.mjs).
+  OPERATOR: 'operator',
 });
 
 export const ROLE_CAPABILITIES = Object.freeze({
@@ -88,6 +91,7 @@ export const ROLE_CAPABILITIES = Object.freeze({
     sync: true,
     deploy: true,
     requestChanges: false,
+    operate: true, // the owner can also drive the operator allowlist locally
   },
   viewer: {
     chat: true,
@@ -100,6 +104,7 @@ export const ROLE_CAPABILITIES = Object.freeze({
     sync: false,
     deploy: false,
     requestChanges: false,
+    operate: false,
   },
   client: {
     chat: true,
@@ -112,6 +117,24 @@ export const ROLE_CAPABILITIES = Object.freeze({
     sync: false,
     deploy: false,
     requestChanges: true,
+    operate: false,
+  },
+  // Operator: remote diagnose + a curated remediation allowlist. Read-only on
+  // chat (can SEE the conversation to help, cannot drive the agent — chatWrite
+  // stays false), plus the `operate` capability the /api/operator/* routes gate
+  // on. Reachable only with the dedicated operator token (operator.mjs).
+  operator: {
+    chat: true,
+    chatWrite: false,
+    preview: true,
+    fileTree: true,
+    terminal: false,
+    inbox: false,
+    share: false,
+    sync: false,
+    deploy: false,
+    requestChanges: false,
+    operate: true,
   },
 });
 
@@ -231,6 +254,13 @@ export function buildConfig(overrides = {}) {
       overrides.shareSecret ||
       env.WILD_WORKSPACE_SHARE_SECRET ||
       secrets().shareSecret,
+    // The operator-channel token — null unless the user explicitly enabled the
+    // channel (`wild-workspace operator enable`). Off by default. Server-side
+    // only; never broadcast to the browser.
+    operatorToken:
+      overrides.operatorToken ??
+      env.WILD_WORKSPACE_OPERATOR_TOKEN ??
+      loadOperatorToken(dataDir),
     workspaceId:
       overrides.workspaceId ||
       env.WILD_WORKSPACE_ID ||

package/server/src/daemon-bin.mjs

@@ -36,9 +36,13 @@ export function daemonBinaryName() {
  *
  * @param {{ env?: NodeJS.ProcessEnv, vendorRoot?: string }} [opts]
  */
-export function resolveDaemonBinary({ env = process.env, vendorRoot } = {}) {
+export function resolveDaemonBinary({ env = process.env, vendorRoot, requireResolve } = {}) {
   const binName = daemonBinaryName();
   const tag = platformTag();
+  // Injected seam: lets a test simulate "the platform subpackage isn't
+  // installed" deterministically, regardless of what's in this machine's
+  // node_modules (the win32-x64 subpackage IS present on a Windows dev box).
+  const resolvePkg = requireResolve || ((id) => require.resolve(id));
 
   // 1. explicit override — if set but missing, that's an error, not a miss.
   const override = env.WILD_WORKSPACE_DAEMON_BIN;
@@ -49,7 +53,7 @@ export function resolveDaemonBinary({ env = process.env, vendorRoot } = {}) {
   // 2. per-platform npm subpackage — resolve via its package.json so the
   //    lookup doesn't depend on an `exports` map for the binary file.
   try {
-    const pkgJson = require.resolve(`@venturewild/workspace-daemon-${tag}/package.json`);
+    const pkgJson = resolvePkg(`@venturewild/workspace-daemon-${tag}/package.json`);
     const candidate = path.join(path.dirname(pkgJson), binName);
     if (existsSync(candidate)) return { path: candidate, source: 'subpackage' };
   } catch {

package/server/src/doctor.mjs

@@ -0,0 +1,246 @@
+// `wild-workspace doctor` — one pre/post-flight diagnostic for a real user's
+// machine. The riskiest moment for a brand-new (non-technical) user is the
+// install itself: no Claude yet, wrong Node, a busy port, a daemon binary that
+// didn't resolve, an unclaimed slug. When something breaks we need to SEE it —
+// ideally fix it — without making them feel stupid (docs/user-experience.md §5).
+//
+// runDoctor() returns a structured report (every check is { id, label, status,
+// detail, hint }); the CLI renders it with ✅/⚠️/❌ and the operator channel
+// serves the same JSON. Every external touch-point (agent detect, auth probe,
+// daemon resolve, port check, account load, service status, registry fetch) is
+// an injected seam so the test suite never spawns a process or hits the network.
+
+import os from 'node:os';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { buildConfig, APP_VERSION } from './config.mjs';
+import { detectAgents, pickDefaultAgent } from './agent.mjs';
+import { probeAgentReadiness } from './agent-readiness.mjs';
+import { resolveDaemonBinary } from './daemon-bin.mjs';
+import { checkPort } from './preview.mjs';
+import { loadAccount } from './account.mjs';
+import { serviceStatus } from './service.mjs';
+import { probeHealth } from './supervisor.mjs';
+import { listLogs, diagnosticsDir } from './logpaths.mjs';
+
+const STATUS_ICON = { ok: '✅', warn: '⚠️', fail: '❌', info: 'ℹ️' };
+
+// Native installer is Claude's canonical path today (npm i -g still works as a
+// fallback). Shown verbatim to the user, so keep it copy-pasteable.
+const CLAUDE_INSTALL_HINT =
+  'Install Claude Code: curl -fsSL https://claude.ai/install.sh | bash  (Windows: irm https://claude.ai/install.ps1 | iex)';
+
+function nodeMajor(version = process.version) {
+  const m = /^v?(\d+)/.exec(String(version));
+  return m ? Number(m[1]) : 0;
+}
+
+// Reach the bmo-sync registry: resolve the user's slug if linked, else /health.
+async function probeRegistry(config, fetchImpl) {
+  const base = String(config.bmoSyncServerUrl || '').replace(/\/$/, '');
+  const slug = config.account?.slug || null;
+  const url = slug
+    ? `${base}/api/slug/resolve/${encodeURIComponent(slug)}`
+    : `${base}/api/health`;
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), 5000);
+  try {
+    const res = await fetchImpl(url, { signal: ctrl.signal });
+    return { reachable: true, status: res.status, slug, url };
+  } catch (e) {
+    return { reachable: false, error: String(e?.message || e), slug, url };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Run every diagnostic check. All deps are injectable for testing.
+ * @returns {{version,generatedAt,platform,summary,checks,logs}}
+ */
+export async function runDoctor(opts = {}, deps = {}) {
+  const config = opts.config || deps.config || buildConfig({});
+  const env = deps.env || process.env;
+  const d = {
+    detectAgents: deps.detectAgents || detectAgents,
+    probeReadiness: deps.probeAgentReadiness || probeAgentReadiness,
+    resolveDaemon: deps.resolveDaemonBinary || resolveDaemonBinary,
+    checkPort: deps.checkPort || checkPort,
+    loadAccount: deps.loadAccount || loadAccount,
+    serviceStatus: deps.serviceStatus || serviceStatus,
+    listLogs: deps.listLogs || listLogs,
+    fetchImpl: deps.fetchImpl || ((...a) => globalThis.fetch(...a)),
+  };
+  const checks = [];
+  const add = (c) => checks.push(c);
+  // Run a check body, capturing a thrown error as a non-fatal 'warn' so one bad
+  // check never aborts the whole report.
+  const guarded = async (id, label, body) => {
+    try {
+      add({ id, label, ...(await body()) });
+    } catch (e) {
+      add({ id, label, status: 'warn', detail: `check errored: ${String(e?.message || e)}`, hint: null });
+    }
+  };
+
+  // 1. Node runtime
+  await guarded('node', 'Node.js runtime', async () => {
+    const major = nodeMajor();
+    const detail = `${process.version} on ${os.platform()}-${os.arch()}`;
+    return major >= 18
+      ? { status: 'ok', detail, hint: null }
+      : { status: 'fail', detail, hint: 'Claude Code + wild-workspace need Node 18 or newer. Update Node, then retry.' };
+  });
+
+  // 2. Claude installed?
+  let claude = null;
+  await guarded('agent', 'Claude Code installed', async () => {
+    const agents = await d.detectAgents();
+    claude = (agents || []).find((a) => a.id === 'claude' && a.available) || null;
+    if (!claude) {
+      const fallback = pickDefaultAgent(agents || []);
+      if (fallback?.available) {
+        return { status: 'info', detail: `Claude not found; using ${fallback.label}.`, hint: null };
+      }
+      return { status: 'fail', detail: 'no `claude` on PATH', hint: CLAUDE_INSTALL_HINT };
+    }
+    return { status: 'ok', detail: claude.resolvedPath || claude.binary, hint: null };
+  });
+
+  // 3. Claude signed in AND able to run turns?
+  if (claude) {
+    await guarded('agentAuth', 'Claude ready to think', async () => {
+      const v = await d.probeReadiness(claude, undefined, env);
+      switch (v.status) {
+        case 'ready':
+          return { status: 'ok', detail: v.email ? `signed in as ${v.email}` : 'signed in', hint: null };
+        case 'subscribe':
+          return {
+            status: 'warn',
+            detail: v.email ? `signed in as ${v.email}, no active plan` : 'signed in, no active plan',
+            hint: 'Claude Code needs a Claude Pro plan (or higher). Subscribe at claude.ai, then retry.',
+          };
+        case 'login':
+          return { status: 'fail', detail: 'not signed in', hint: 'Run `claude auth login`, sign in, then retry.' };
+        case 'missing':
+          return { status: 'fail', detail: 'Claude not installed', hint: CLAUDE_INSTALL_HINT };
+        default:
+          return { status: 'info', detail: `readiness unknown (${v.status})`, hint: 'Will be confirmed on the first agent turn.' };
+      }
+    });
+  }
+
+  // 4. bmo-sync daemon binary resolvable?
+  await guarded('daemonBinary', 'Sync daemon binary', async () => {
+    const r = d.resolveDaemon({ env });
+    if (!r) {
+      return { status: 'fail', detail: 'WILD_WORKSPACE_DAEMON_BIN is set but the file is missing', hint: 'Unset it or point it at a real binary.' };
+    }
+    if (r.source === 'path') {
+      return {
+        status: 'warn',
+        detail: 'no bundled daemon found — relying on PATH; cross-device sync may be off',
+        hint: 'Reinstall: npm i -g @venturewild/workspace (pulls the daemon for your platform).',
+      };
+    }
+    return { status: 'ok', detail: `${r.path} (${r.source})`, hint: null };
+  });
+
+  // 5. Workspace port
+  await guarded('port', `Workspace port :${config.port}`, async () => {
+    const inUse = await d.checkPort(config.port);
+    return inUse
+      ? { status: 'info', detail: 'in use — your workspace is likely already running (or another app holds it)', hint: null }
+      : { status: 'ok', detail: 'free', hint: null };
+  });
+
+  // 6. Account linked (slug)
+  let account = null;
+  await guarded('account', 'Workspace account linked', async () => {
+    account = d.loadAccount(config.dataDir);
+    if (account?.slug) {
+      return { status: 'ok', detail: `${account.slug} (${account.email || 'no email'}) → https://${account.slug}.venturewild.llc`, hint: null };
+    }
+    return { status: 'warn', detail: 'not linked yet', hint: 'Run `wild-workspace login <blob>` with the code from workspace.venturewild.llc.' };
+  });
+
+  // 7. Registry reachable + slug status
+  await guarded('registry', 'Sync server reachable', async () => {
+    const r = await probeRegistry({ ...config, account: account || config.account }, d.fetchImpl);
+    if (!r.reachable) {
+      return { status: 'fail', detail: `can't reach ${r.url}: ${r.error}`, hint: 'Check the internet connection, then retry.' };
+    }
+    if (r.slug) {
+      if (r.status === 200) return { status: 'ok', detail: `slug "${r.slug}" is claimed`, hint: null };
+      if (r.status === 404) return { status: 'warn', detail: `slug "${r.slug}" is not claimed on the server`, hint: 'Re-run the claim, or `wild-workspace login` with a fresh blob.' };
+      return { status: 'warn', detail: `slug resolve returned HTTP ${r.status}`, hint: null };
+    }
+    return r.status < 500
+      ? { status: 'ok', detail: `reachable (HTTP ${r.status})`, hint: null }
+      : { status: 'warn', detail: `server returned HTTP ${r.status}`, hint: null };
+  });
+
+  // 8. Always-on / autostart
+  await guarded('service', 'Always-on (autostart)', async () => {
+    const s = await d.serviceStatus({ port: config.port }, { probeImpl: (p) => probeHealth(p) });
+    if (s.supported === false) {
+      return { status: 'info', detail: `not yet on ${s.platform} — run \`wild-workspace\` to start it`, hint: null };
+    }
+    const bits = [`installed=${s.installed ? 'yes' : 'no'}`, `supervisor=${s.supervisorAlive ? 'up' : 'down'}`, `server=${s.serverUp ? 'up' : 'down'}`];
+    return { status: s.installed ? 'ok' : 'info', detail: bits.join(' '), hint: s.installed ? null : 'Enable with `wild-workspace service install`.' };
+  });
+
+  const logs = d.listLogs(env);
+  const summary = checks.reduce(
+    (acc, c) => ((acc[c.status] = (acc[c.status] || 0) + 1), acc),
+    { ok: 0, warn: 0, fail: 0, info: 0 },
+  );
+
+  return {
+    version: APP_VERSION,
+    generatedAt: new Date().toISOString(),
+    platform: `${os.platform()}-${os.arch()}`,
+    summary,
+    checks,
+    logs,
+  };
+}
+
+// Render a report to a human string (used by the CLI). The operator channel
+// sends the JSON instead.
+export function renderDoctor(report) {
+  const lines = [];
+  lines.push(`wild-workspace doctor — v${report.version}  (${report.platform})`);
+  lines.push('');
+  for (const c of report.checks) {
+    lines.push(`${STATUS_ICON[c.status] || '•'}  ${c.label}: ${c.detail}`);
+    if (c.hint && (c.status === 'fail' || c.status === 'warn')) {
+      lines.push(`      → ${c.hint}`);
+    }
+  }
+  lines.push('');
+  const { ok, warn, fail } = report.summary;
+  lines.push(`Summary: ${ok} ok · ${warn} warning${warn === 1 ? '' : 's'} · ${fail} problem${fail === 1 ? '' : 's'}`);
+  lines.push('');
+  lines.push('Logs:');
+  for (const l of report.logs) {
+    lines.push(`  ${l.exists ? '·' : ' '} ${l.name.padEnd(10)} ${l.file}${l.exists ? ` (${l.size} bytes)` : ' (none yet)'}`);
+  }
+  return lines.join('\n');
+}
+
+// Persist the JSON report under ~/.wild-workspace/diagnostics/. Returns the
+// file path (or null if it couldn't be written). Best-effort.
+export function writeDoctorBundle(report, env = process.env) {
+  try {
+    const dir = diagnosticsDir(env);
+    fs.mkdirSync(dir, { recursive: true });
+    const stamp = report.generatedAt.replace(/[:.]/g, '-');
+    const file = path.join(dir, `doctor-${stamp}.json`);
+    fs.writeFileSync(file, JSON.stringify(report, null, 2));
+    return file;
+  } catch {
+    return null;
+  }
+}

package/server/src/index.mjs

@@ -25,11 +25,19 @@ import { listDir, readFile, fullTree, workspaceSummary, safeResolve } from './fs
 import { InboxWatcher } from './inbox.mjs';
 import { ActivityBus } from './activity.mjs';
 import { loadIdentity, saveIdentity, markOnboarded, TONES } from './agent-identity.mjs';
+import { probeAgentReadiness } from './agent-readiness.mjs';
 import { ErrorReporter } from './error-reporter.mjs';
 import { DaemonBridge } from './daemon.mjs';
 import { DaemonSupervisor } from './daemon-supervisor.mjs';
 import { SyncControl } from './sync.mjs';
 import { detectPreviewPorts, checkPort } from './preview.mjs';
+import { loadAccount } from './account.mjs';
+import { runDoctor } from './doctor.mjs';
+import { appendLine, tailFile, logFile, TAILABLE, globalDir } from './logpaths.mjs';
+import { SessionReporter } from './session-reporter.mjs';
+import { TranscriptRecorder } from './transcript.mjs';
+import { loadObservabilityConsent, setObservabilityConsent } from './observability.mjs';
+import { spawn } from 'node:child_process';
 import { nanoid } from 'nanoid';
 
 const __filename = url.fileURLToPath(import.meta.url);
@@ -166,6 +174,73 @@ export async function createServer(overrides = {}) {
           enabled: process.env.WILD_WORKSPACE_NO_TELEMETRY !== '1',
         });
 
+  // Proactive, consented session + install observability (session-reporter.mjs).
+  // Default-on with a clear disclosure at onboarding; off via the consent toggle
+  // or the WILD_WORKSPACE_NO_TELEMETRY kill switch. Inert in tests and without an
+  // account token. Carries WHAT happened + install health, never the words —
+  // conversation content is the separate transcript channel.
+  let observability = loadObservabilityConsent(config.dataDir);
+  const sessionEnabled = () =>
+    observability.enabled &&
+    process.env.WILD_WORKSPACE_NO_TELEMETRY !== '1' &&
+    !process.env.VITEST &&
+    config.nodeEnv !== 'test';
+  const sessionReporter =
+    overrides.sessionReporter === false
+      ? { ingest() {}, flush() {}, start() {}, stop() {}, setEnabled() {} }
+      : overrides.sessionReporter ||
+        new SessionReporter({
+          bmoSyncUrl: config.bmoSyncServerUrl,
+          accountToken: config.accountToken,
+          slug: config.account?.slug || null,
+          workspaceId: config.workspaceId,
+          sessionId: overrides.sessionId || nanoid(12),
+          enabled: sessionEnabled(),
+        });
+  // Conversation *content* channel (transcript.mjs) — separate from the feed.
+  // Appends markdown to ~/.wild-workspace/transcripts/<workspaceId>/ (OUTSIDE the
+  // synced repo); forwarding to us is consent-gated. Noop under the test runner so
+  // it never writes into a real home dir.
+  const transcriptForward = ({ markdown, date }) => {
+    if (!sessionEnabled() || !config.accountToken) return;
+    const url = `${config.bmoSyncServerUrl.replace(/\/$/, '')}/api/telemetry`;
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), 5000);
+    Promise.resolve()
+      .then(() =>
+        fetch(url, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({
+            account_token: config.accountToken,
+            slug: config.account?.slug || null,
+            workspace_id: config.workspaceId,
+            kind: 'transcript',
+            date,
+            markdown,
+            sent_at: Math.floor(Date.now() / 1000),
+          }),
+          signal: ctrl.signal,
+        }),
+      )
+      .catch(() => {})
+      .finally(() => clearTimeout(t));
+  };
+  const transcriptRecorder =
+    overrides.transcriptRecorder === false || process.env.VITEST || config.nodeEnv === 'test'
+      ? { ingest() {}, flush() {}, stop() {} }
+      : new TranscriptRecorder({
+          dir: path.join(globalDir(), 'transcripts', config.workspaceId),
+          agentName: loadIdentity(config.dataDir)?.name || activeAgent?.label || 'Agent',
+          forwardImpl: transcriptForward,
+        });
+
+  activityBus.on('event', (e) => {
+    try { sessionReporter.ingest(e); } catch { /* never let telemetry break the bus */ }
+    try { transcriptRecorder.ingest(e); } catch { /* nor the transcript */ }
+  });
+  sessionReporter.start();
+
   // --- chat turn orchestration ----------------------------------------------
   // One conversation per workspace in v1 (single-user, single tab — PRD §5.5).
   // Both user sends and auto-wake turns thread through one turn-runner so they
@@ -358,6 +433,12 @@ export async function createServer(overrides = {}) {
       if (token === config.partnerToken) {
         return { role: ROLES.PARTNER, sub: 'partner', source: 'partner-token' };
       }
+      // The operator (support) token — header-only, and only when the channel is
+      // explicitly enabled (a token exists). Never accepted via `?t=` (below),
+      // so it can't leak through URLs/logs/referrer (SECURITY.md S1).
+      if (config.operatorToken && token === config.operatorToken) {
+        return { role: ROLES.OPERATOR, sub: 'operator', source: 'operator-token' };
+      }
       const payload = await verifyShareToken(token, config.shareSecret);
       if (payload && !tokenRegistry.isRevoked(payload.sub)) {
         return {
@@ -456,6 +537,9 @@ export async function createServer(overrides = {}) {
       // with the actual <slug>.venturewild.llc URL. accountToken is NOT
       // exposed — it stays in server-side config only.
       account: config.account,
+      // Consent state for the proactive observability feed, so settings/onboarding
+      // can show + toggle it. The disclosure copy lives in the UI.
+      observability: { enabled: observability.enabled, version: observability.version },
     });
   });
 
@@ -467,6 +551,33 @@ export async function createServer(overrides = {}) {
     return c.json({ identity, tones: TONES });
   });
 
+  // --- agent readiness (the agent-login gate) ---
+  // "Is the wrapped agent installed AND signed in?" detectAgents() only proves
+  // the binary is on PATH; this proves a turn will actually work. Onboarding
+  // calls this before its folder-peek wow beat so a not-signed-in user gets a
+  // calm "sign in to Claude" step instead of a broken error bubble (the §3.2
+  // open question in docs/user-experience.md). See agent-readiness.mjs.
+  //
+  // Cached briefly: a 'ready' verdict rarely flips, and the probe spawns a
+  // subprocess. `?fresh=1` forces a re-probe (the gate's "I've signed in" button
+  // sends it so the user isn't stuck behind a stale 'login' verdict).
+  let _readinessCache = null; // { at, verdict }
+  const READINESS_TTL_MS = 30_000;
+  const agentTag = (a) => (a ? { id: a.id, label: a.label } : null);
+  app.get('/api/agent/readiness', async (c) => {
+    const forbidden = require(c, 'chat');
+    if (forbidden) return forbidden;
+    const fresh = c.req.query('fresh') === '1';
+    const now = Date.now();
+    if (!fresh && _readinessCache && now - _readinessCache.at < READINESS_TTL_MS) {
+      return c.json({ agent: agentTag(activeAgent), ...(_readinessCache.verdict) });
+    }
+    const verdict = await probeAgentReadiness(activeAgent);
+    _readinessCache = { at: now, verdict };
+    log('[onboarding]', `readiness agent=${activeAgent?.id || '-'} status=${verdict.status}${verdict.email ? ` email=${verdict.email}` : ''}`);
+    return c.json({ agent: agentTag(activeAgent), ...verdict });
+  });
+
   app.post('/api/agent/identity', async (c) => {
     const forbidden = require(c, 'chatWrite');
     if (forbidden) return forbidden;
@@ -499,6 +610,20 @@ export async function createServer(overrides = {}) {
     }
   });
 
+  // Consent toggle for the proactive observability feed (default-on — see
+  // observability.mjs). Owner-only; applied live to the reporter, no restart.
+  app.post('/api/observability/consent', async (c) => {
+    const forbidden = require(c, 'chatWrite');
+    if (forbidden) return forbidden;
+    const body = await c.req.json().catch(() => ({}));
+    const enabled = body.enabled !== false;
+    observability = setObservabilityConsent(config.dataDir, enabled);
+    sessionReporter.setEnabled(sessionEnabled());
+    activityBus.publish({ type: 'observability-consent', enabled });
+    log('[observability]', `consent set enabled=${enabled}`);
+    return c.json({ observability: { enabled: observability.enabled, version: observability.version } });
+  });
+
   // --- onboarding step 2: agent peeks at a folder ---
   // The browser sends a small sample of the chosen folder's contents — file
   // names + a short head of each text file — and we ask the agent to react
@@ -637,6 +762,109 @@ export async function createServer(overrides = {}) {
     return c.json({ ok: true, active: activeAgent.id });
   });
 
+  // --- operator channel (consented support; OFF unless a token is set) -------
+  // The dedicated operator token (operator.mjs) maps to the `operator` role in
+  // resolveRole; every route here gates on the `operate` capability. When the
+  // channel is disabled (no token) the routes 404 so the surface is invisible.
+  // Each call is audit-logged to operator.log AND surfaced in the activity feed
+  // (CLAUDE.md principle #5 — both peers see what happened). The actions are a
+  // CURATED ALLOWLIST — never arbitrary shell (docs/SECURITY.md).
+  const operatorDeps = {
+    runDoctor: (o) => runDoctor(o),
+    detectAgents,
+    loadAccount,
+    spawn,
+    ...(overrides.operatorDeps || {}),
+  };
+  const operatorEnabled = () => Boolean(config.operatorToken);
+  function auditOperator(c, action, detail) {
+    const s = c.get('session') || {};
+    appendLine('operator', `${action} by=${s.sub || 'operator'} src=${s.source || '-'} ${detail || ''}`.trim());
+    activityBus.publish({ type: 'operator-action', action, detail: detail || null, at: Date.now() });
+  }
+
+  // Curated remediation actions. Each reuses an existing seam; none runs an
+  // arbitrary command. (`restart-server` is intentionally absent — exiting the
+  // process would sever the very tunnel we reach the user through on a machine
+  // without the always-on supervisor; deferred — see SECURITY.md.)
+  const OPERATOR_ACTIONS = {
+    'run-doctor': async () => operatorDeps.runDoctor({ config }),
+    'restart-daemon': async () => {
+      if (!daemonSupervisor) return { restarted: false, reason: 'daemon-supervisor-disabled' };
+      await daemonSupervisor.stop().catch(() => {});
+      return daemonSupervisor.ensureRunning();
+    },
+    'relink-account': async () => {
+      const account = operatorDeps.loadAccount(config.dataDir);
+      if (daemonSupervisor) {
+        await daemonSupervisor.stop().catch(() => {});
+        await daemonSupervisor.ensureRunning().catch(() => {});
+      }
+      return { relinked: Boolean(account?.slug), slug: account?.slug || null, email: account?.email || null };
+    },
+    'redetect-agent': async () => {
+      const agents = (await operatorDeps.detectAgents()) || [];
+      const next = pickDefaultAgent(agents) || null;
+      activeAgent = next;
+      _readinessCache = null; // force a fresh readiness probe next time
+      activityBus.publish({ type: 'agent-changed', agentId: next?.id || null });
+      return {
+        active: next?.id || null,
+        available: Boolean(next?.available),
+        agents: agents.map((a) => ({ id: a.id, available: a.available })),
+      };
+    },
+    'reinstall-daemon': async () => {
+      const cmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+      const child = operatorDeps.spawn(cmd, ['i', '-g', '@venturewild/workspace'], { windowsHide: true });
+      appendLine('operator', `reinstall-daemon spawned pid=${child?.pid}`);
+      child?.stdout?.on?.('data', (d) => appendLine('operator', `[npm] ${String(d).trim()}`));
+      child?.stderr?.on?.('data', (d) => appendLine('operator', `[npm:err] ${String(d).trim()}`));
+      child?.on?.('exit', (code) => appendLine('operator', `reinstall-daemon exited code=${code}`));
+      return { started: true, pid: child?.pid || null, command: `${cmd} i -g @venturewild/workspace` };
+    },
+  };
+
+  app.get('/api/operator/diag', async (c) => {
+    if (!operatorEnabled()) return c.json({ error: 'operator-disabled' }, 404);
+    const forbidden = require(c, 'operate');
+    if (forbidden) return forbidden;
+    const report = await operatorDeps.runDoctor({ config });
+    auditOperator(c, 'diag', `fail=${report.summary?.fail} warn=${report.summary?.warn}`);
+    return c.json(report);
+  });
+
+  app.get('/api/operator/logs', (c) => {
+    if (!operatorEnabled()) return c.json({ error: 'operator-disabled' }, 404);
+    const forbidden = require(c, 'operate');
+    if (forbidden) return forbidden;
+    const name = c.req.query('name') || 'cli';
+    if (!TAILABLE.includes(name)) return c.json({ error: 'unknown-log', name, allowed: TAILABLE }, 400);
+    const tail = Math.min(Number(c.req.query('tail')) || 200, 2000);
+    const file = logFile(name);
+    auditOperator(c, 'logs', `name=${name} tail=${tail}`);
+    return c.json({ name, file, tail, body: tailFile(file, tail) });
+  });
+
+  app.post('/api/operator/action', async (c) => {
+    if (!operatorEnabled()) return c.json({ error: 'operator-disabled' }, 404);
+    const forbidden = require(c, 'operate');
+    if (forbidden) return forbidden;
+    const body = await c.req.json().catch(() => ({}));
+    const action = String(body.action || '');
+    if (!OPERATOR_ACTIONS[action]) {
+      return c.json({ error: 'unknown-action', action, allowed: Object.keys(OPERATOR_ACTIONS) }, 400);
+    }
+    auditOperator(c, 'action', `action=${action}`);
+    try {
+      const result = await OPERATOR_ACTIONS[action]();
+      return c.json({ ok: true, action, result });
+    } catch (e) {
+      appendLine('operator', `action=${action} FAILED ${e?.stack || e}`);
+      return c.json({ ok: false, action, error: String(e?.message || e) }, 500);
+    }
+  });
+
   // --- workspace files ---
   app.get('/api/workspace/tree', async (c) => {
     if (!ROLE_CAPABILITIES[c.get('role')].fileTree) {
@@ -1053,11 +1281,14 @@ export async function createServer(overrides = {}) {
     daemonSupervisor,
     daemonReady,
     syncControl,
+    sessionReporter,
     detectedAgents,
     getActiveAgent: () => activeAgent,
     async stop() {
       try { clearTimeout(autoWakeTimer); } catch {}
       try { currentTurn?.session.close(); } catch {}
+      try { sessionReporter.stop(); } catch {}
+      try { transcriptRecorder.stop(); } catch {}
       try { inboxWatcher.stop(); } catch {}
       try { daemonBridge?.stop(); } catch {}
       // The daemon is deliberately NOT stopped here — it is detached so sync