zam-core 0.3.13 → 0.4.1

package/dist/cli/index.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 
 // src/cli/index.ts
-import { readFileSync as readFileSync13 } from "fs";
-import { dirname as dirname10, join as join21 } from "path";
+import { readFileSync as readFileSync14 } from "fs";
+import { dirname as dirname10, join as join22 } from "path";
 import { fileURLToPath as fileURLToPath5 } from "url";
-import { Command as Command23 } from "commander";
+import { Command as Command24 } from "commander";
 
 // src/cli/commands/agent.ts
 import { existsSync as existsSync11 } from "fs";
-import { join as join10 } from "path";
+import { join as join11 } from "path";
 import { Command } from "commander";
 
 // src/kernel/analytics/stats.ts
@@ -703,6 +703,66 @@ function isRemoteDatabasePath(dbPath) {
 function isDatabaseProvider(value) {
   return value === "local" || value === "native" || value === "remote";
 }
+function cwdRequiresTursoCredentials() {
+  try {
+    const configPath = join2(process.cwd(), ".zam", "config.yaml");
+    if (existsSync2(configPath)) {
+      const configText = readFileSync2(configPath, "utf-8");
+      return /[\s\S]*turso:[\s\S]*url:/m.test(configText);
+    }
+  } catch (_e) {
+  }
+  return false;
+}
+function resolveDatabaseTarget(options = {}) {
+  const configuredCloud = options.useConfiguredCloud !== false && !options.dbPath && !options.syncUrl ? getTursoCredentials() : null;
+  if (cwdRequiresTursoCredentials() && !configuredCloud && options.useConfiguredCloud !== false && !options.dbPath && !options.syncUrl) {
+    throw new Error(
+      "Turso cloud database is configured in .zam/config.yaml but missing local credentials. Run: zam connector setup turso"
+    );
+  }
+  const dbPath = configuredCloud?.url ?? options.dbPath ?? DEFAULT_DB_PATH;
+  const isRemote = isRemoteDatabasePath(dbPath);
+  const isEmbeddedReplica = Boolean(options.syncUrl);
+  const provider = resolveProvider(options, configuredCloud?.mode, isRemote);
+  return {
+    dbPath,
+    provider,
+    isRemote,
+    isEmbeddedReplica,
+    configuredCloud
+  };
+}
+function getDatabaseTargetInfo(options = {}) {
+  const target = resolveDatabaseTarget(options);
+  if (target.isEmbeddedReplica) {
+    return {
+      kind: "turso-replica",
+      provider: target.provider,
+      location: target.dbPath,
+      syncUrl: options.syncUrl
+    };
+  }
+  if (target.provider === "remote" && target.isRemote) {
+    return {
+      kind: "turso-remote",
+      provider: target.provider,
+      location: target.dbPath
+    };
+  }
+  if (target.isRemote) {
+    return {
+      kind: "turso-native",
+      provider: target.provider,
+      location: target.dbPath
+    };
+  }
+  return {
+    kind: "local",
+    provider: target.provider,
+    location: target.dbPath
+  };
+}
 function openLocalSqlite(dbPath) {
   const mod = require2("better-sqlite3");
   const BetterSqlite3 = "default" in mod ? mod.default : mod;
@@ -720,27 +780,7 @@ function loadLibsql() {
   }
 }
 async function openDatabase(options = {}) {
-  const configuredCloud = options.useConfiguredCloud !== false && !options.dbPath && !options.syncUrl ? getTursoCredentials() : null;
-  let requiresTurso = false;
-  try {
-    const configPath = join2(process.cwd(), ".zam", "config.yaml");
-    if (existsSync2(configPath)) {
-      const configText = readFileSync2(configPath, "utf-8");
-      if (/[\s\S]*turso:[\s\S]*url:/m.test(configText)) {
-        requiresTurso = true;
-      }
-    }
-  } catch (_e) {
-  }
-  if (requiresTurso && !configuredCloud && options.useConfiguredCloud !== false && !options.dbPath && !options.syncUrl) {
-    throw new Error(
-      "Turso cloud database is configured in .zam/config.yaml but missing local credentials. Run: zam connector setup turso"
-    );
-  }
-  const dbPath = configuredCloud?.url ?? options.dbPath ?? DEFAULT_DB_PATH;
-  const isRemote = isRemoteDatabasePath(dbPath);
-  const isEmbeddedReplica = Boolean(options.syncUrl);
-  const provider = resolveProvider(options, configuredCloud?.mode, isRemote);
+  const { dbPath, provider, isRemote, isEmbeddedReplica, configuredCloud } = resolveDatabaseTarget(options);
   const shouldInitialize = options.initialize === true || !isRemote && !isEmbeddedReplica && !existsSync2(dbPath);
   if (provider === "remote") {
     const url = isRemote ? dbPath : options.syncUrl;
@@ -2086,6 +2126,415 @@ function getMonitorLogStats(sessionId) {
   return { exists: true, sizeBytes: stat.size, lineCount };
 }
 
+// src/kernel/observation/observer-sidecar-policy.ts
+import { mkdirSync as mkdirSync5, writeFileSync as writeFileSync3 } from "fs";
+import { join as join6 } from "path";
+
+// src/kernel/observation/policy.ts
+var OBSERVER_POLICY_VERSION = 1;
+var DEFAULT_OBSERVER_POLICY = {
+  version: OBSERVER_POLICY_VERSION,
+  scope: "window",
+  allowlist: [],
+  denylist: [],
+  consent: "per-session",
+  retention: "none",
+  redactWindowTitles: true,
+  audioOptIn: false
+};
+var BUILT_IN_SENSITIVE_MATCHERS = [
+  // Password managers
+  "1password",
+  "bitwarden",
+  "keepass",
+  "lastpass",
+  "dashlane",
+  "nordpass",
+  "enpass",
+  "proton pass",
+  // Authentication / credential / UAC surfaces
+  "credentialuibroker",
+  "consentux",
+  "logonui",
+  "windowssecurity",
+  "authenticator",
+  // Conservative banking/title hints
+  "online banking",
+  "onlinebanking"
+];
+function parseList(raw) {
+  if (!raw) return [];
+  return raw.split(",").map((entry) => entry.trim().toLowerCase()).filter((entry) => entry.length > 0);
+}
+function parseObserverList(raw) {
+  return parseList(raw);
+}
+function parseScope(raw, defaultScope) {
+  if (raw === "off" || raw === "window" || raw === "fullscreen") {
+    return raw;
+  }
+  return defaultScope ?? DEFAULT_OBSERVER_POLICY.scope;
+}
+function parseConsent(raw, defaultConsent) {
+  if (raw === "per-capture" || raw === "per-session" || raw === "standing") {
+    return raw;
+  }
+  return defaultConsent ?? DEFAULT_OBSERVER_POLICY.consent;
+}
+function parseRetention(raw) {
+  return raw === "none" || raw === "session" || raw === "persist" ? raw : DEFAULT_OBSERVER_POLICY.retention;
+}
+function parseBool(raw, fallback) {
+  if (raw === void 0) return fallback;
+  return raw === "true";
+}
+function parseObserverPolicy(raw, defaults) {
+  return {
+    version: OBSERVER_POLICY_VERSION,
+    scope: parseScope(raw["observer.scope"], defaults?.scope),
+    allowlist: parseList(raw["observer.allowlist"]),
+    denylist: parseList(raw["observer.denylist"]),
+    consent: parseConsent(raw["observer.consent"], defaults?.consent),
+    retention: parseRetention(raw["observer.retention"]),
+    redactWindowTitles: parseBool(
+      raw["observer.redact_titles"],
+      DEFAULT_OBSERVER_POLICY.redactWindowTitles
+    ),
+    audioOptIn: parseBool(
+      raw["observer.audio"],
+      DEFAULT_OBSERVER_POLICY.audioOptIn
+    )
+  };
+}
+function getDefaultsForSymbiosisMode(mode) {
+  if (mode === "autonomy") {
+    return { scope: "fullscreen", consent: "standing" };
+  }
+  return { scope: "window", consent: "per-session" };
+}
+async function resolveActiveSymbiosisMode(db) {
+  const userId = await getSetting(db, "user.id") || "default";
+  const activeSession = await db.prepare(
+    "SELECT id FROM sessions WHERE user_id = ? AND completed_at IS NULL ORDER BY started_at DESC LIMIT 1"
+  ).get(userId);
+  if (activeSession) {
+    const stepToken = await db.prepare(
+      `SELECT t.symbiosis_mode, t.domain
+         FROM session_steps s
+         JOIN tokens t ON t.id = s.token_id
+         WHERE s.session_id = ?
+         ORDER BY s.created_at DESC, s.id DESC
+         LIMIT 1`
+    ).get(activeSession.id);
+    if (stepToken) {
+      if (stepToken.symbiosis_mode) {
+        return stepToken.symbiosis_mode;
+      }
+      if (stepToken.domain) {
+        const competence = await getDomainCompetence(db, userId);
+        const comp = competence.find((c) => c.domain === stepToken.domain);
+        if (comp) {
+          return comp.suggestedMode;
+        }
+      }
+    }
+  }
+  const lastReviewToken = await db.prepare(
+    `SELECT t.symbiosis_mode, t.domain
+       FROM review_logs r
+       JOIN tokens t ON t.id = r.token_id
+       WHERE r.user_id = ?
+       ORDER BY r.reviewed_at DESC, r.id DESC
+       LIMIT 1`
+  ).get(userId);
+  if (lastReviewToken) {
+    if (lastReviewToken.symbiosis_mode) {
+      return lastReviewToken.symbiosis_mode;
+    }
+    if (lastReviewToken.domain) {
+      const competence = await getDomainCompetence(db, userId);
+      const comp = competence.find((c) => c.domain === lastReviewToken.domain);
+      if (comp) {
+        return comp.suggestedMode;
+      }
+    }
+  }
+  return "shadowing";
+}
+async function resolveObserverPolicy(db) {
+  const [scope, allowlist, denylist, consent, retention, redactTitles, audio] = await Promise.all([
+    getSetting(db, "observer.scope"),
+    getSetting(db, "observer.allowlist"),
+    getSetting(db, "observer.denylist"),
+    getSetting(db, "observer.consent"),
+    getSetting(db, "observer.retention"),
+    getSetting(db, "observer.redact_titles"),
+    getSetting(db, "observer.audio")
+  ]);
+  const mode = await resolveActiveSymbiosisMode(db);
+  const defaults = getDefaultsForSymbiosisMode(mode);
+  return parseObserverPolicy(
+    {
+      "observer.scope": scope,
+      "observer.allowlist": allowlist,
+      "observer.denylist": denylist,
+      "observer.consent": consent,
+      "observer.retention": retention,
+      "observer.redact_titles": redactTitles,
+      "observer.audio": audio
+    },
+    defaults
+  );
+}
+function haystacks(...values) {
+  return values.filter((v) => typeof v === "string" && v.length > 0).map((v) => v.toLowerCase());
+}
+function deny(reason, denialReason) {
+  return { allowed: false, reason, denialReason };
+}
+function matchBuiltInSensitive(processName, windowTitle) {
+  const fields = haystacks(processName, windowTitle);
+  for (const matcher of BUILT_IN_SENSITIVE_MATCHERS) {
+    if (fields.some((field) => field.includes(matcher))) return matcher;
+  }
+  return null;
+}
+function matchDenylist(policy, processName, windowTitle) {
+  const fields = haystacks(processName, windowTitle);
+  for (const matcher of policy.denylist) {
+    if (fields.some((field) => field.includes(matcher))) return matcher;
+  }
+  return null;
+}
+function inAllowlist(policy, processName) {
+  if (policy.allowlist.length === 0) return true;
+  if (!processName) return false;
+  const name = processName.toLowerCase();
+  return policy.allowlist.some((entry) => name.includes(entry));
+}
+function decidePreCapture(policy, request) {
+  if (policy.scope === "off") {
+    return deny("observer is disabled (observer.scope=off)", "scope-off");
+  }
+  if (policy.scope === "window" && !request.hasExplicitTarget) {
+    return deny(
+      "window scope requires a target: pass --process-name or --hwnd, or set observer.scope=fullscreen",
+      "scope-requires-target"
+    );
+  }
+  const requested = request.requestedProcessName;
+  if (requested) {
+    const sensitive = matchBuiltInSensitive(requested, null);
+    if (sensitive) {
+      return deny(`refusing sensitive surface (${sensitive})`, "sensitive");
+    }
+    const denied = matchDenylist(policy, requested, null);
+    if (denied) {
+      return deny(`process is denylisted (${denied})`, "denylisted");
+    }
+    if (policy.scope === "window" && !inAllowlist(policy, requested)) {
+      return deny(
+        `process not in observer.allowlist (${requested.toLowerCase()})`,
+        "not-allowlisted"
+      );
+    }
+  }
+  return { allowed: true };
+}
+function decidePostCapture(policy, target) {
+  const isFullscreen = target.method.toLowerCase().includes("fullscreen");
+  if (policy.scope === "window" && isFullscreen) {
+    return deny(
+      "window scope but capture fell back to fullscreen (target window not resolved)",
+      "scope-requires-target"
+    );
+  }
+  const sensitive = matchBuiltInSensitive(
+    target.processName,
+    target.windowTitle
+  );
+  if (sensitive) {
+    return deny(`refusing sensitive surface (${sensitive})`, "sensitive");
+  }
+  const denied = matchDenylist(policy, target.processName, target.windowTitle);
+  if (denied) {
+    return deny(`captured window is denylisted (${denied})`, "denylisted");
+  }
+  if (policy.scope === "window" && !inAllowlist(policy, target.processName)) {
+    return deny(
+      `captured window not in observer.allowlist (${target.processName ?? "unknown"})`,
+      "not-allowlisted"
+    );
+  }
+  return { allowed: true };
+}
+async function isObserverPolicyConfigured(db) {
+  const settings = await getAllSettings(db);
+  return Object.keys(settings).some((key) => key.startsWith("observer."));
+}
+var OBSERVER_POLICY_UNSET_HINT = "Observer policy is at defaults (scope=window: only a targeted window is captured). Configure with `zam observer status|grant|revoke` or `zam settings set observer.scope <off|window|fullscreen>`.";
+
+// src/kernel/observation/ui-observer-io.ts
+import { appendFileSync as appendFileSync2, existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync5 } from "fs";
+import { homedir as homedir4 } from "os";
+import { join as join5 } from "path";
+
+// src/kernel/observation/ui-observer.ts
+var UI_OBSERVATION_PROTOCOL_VERSION = 1;
+var OBSERVATION_KINDS = /* @__PURE__ */ new Set([
+  "progress",
+  "step-completed",
+  "error",
+  "help-seeking",
+  "uncertain",
+  "privacy-pause",
+  "heartbeat"
+]);
+var ACTION_TYPES = /* @__PURE__ */ new Set([
+  "click",
+  "shortcut",
+  "typing",
+  "scroll",
+  "window-change"
+]);
+var EVIDENCE_TYPES = /* @__PURE__ */ new Set([
+  "uia",
+  "keyframe",
+  "clip",
+  "window"
+]);
+function isUiObservationReport(value) {
+  if (!isRecord(value)) return false;
+  if (value.version !== UI_OBSERVATION_PROTOCOL_VERSION) return false;
+  if (!isNonEmptyString(value.sessionId)) return false;
+  if (!isNonNegativeInteger(value.sequence)) return false;
+  if (!isNonEmptyString(value.observedFrom)) return false;
+  if (!isNonEmptyString(value.observedTo)) return false;
+  if (typeof value.kind !== "string" || !OBSERVATION_KINDS.has(value.kind)) {
+    return false;
+  }
+  if (!isApplication(value.application)) return false;
+  if (!isNonEmptyString(value.summary)) return false;
+  if (!Array.isArray(value.actions) || !value.actions.every(isObservedAction)) {
+    return false;
+  }
+  if (!Array.isArray(value.evidence) || !value.evidence.every(isEvidenceRef)) {
+    return false;
+  }
+  if (!Array.isArray(value.candidateTokens) || !value.candidateTokens.every(isCandidateToken)) {
+    return false;
+  }
+  return isConfidence(value.confidence);
+}
+function parseUiObservationLog(jsonl) {
+  const reports = [];
+  for (const line of jsonl.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const value = JSON.parse(trimmed);
+      if (isUiObservationReport(value)) {
+        reports.push(value);
+      }
+    } catch {
+    }
+  }
+  return reports.sort((left, right) => left.sequence - right.sequence);
+}
+function isApplication(value) {
+  if (!isRecord(value) || !isNonEmptyString(value.processName)) return false;
+  if (value.processId !== void 0 && !isNonNegativeInteger(value.processId)) {
+    return false;
+  }
+  return value.windowTitle === void 0 || typeof value.windowTitle === "string";
+}
+function isObservedAction(value) {
+  if (!isRecord(value) || typeof value.type !== "string") return false;
+  if (!ACTION_TYPES.has(value.type)) return false;
+  if (value.target !== void 0 && typeof value.target !== "string") {
+    return false;
+  }
+  return value.result === void 0 || typeof value.result === "string";
+}
+function isEvidenceRef(value) {
+  if (!isRecord(value) || typeof value.type !== "string") return false;
+  return EVIDENCE_TYPES.has(value.type) && isNonEmptyString(value.ref) && typeof value.redacted === "boolean";
+}
+function isCandidateToken(value) {
+  return isRecord(value) && isNonEmptyString(value.slug) && isConfidence(value.confidence) && isNonEmptyString(value.rationale);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function isNonNegativeInteger(value) {
+  return Number.isInteger(value) && Number(value) >= 0;
+}
+function isConfidence(value) {
+  return typeof value === "number" && value >= 0 && value <= 1;
+}
+
+// src/kernel/observation/ui-observer-io.ts
+var DEFAULT_UI_OBSERVER_DIR = join5(homedir4(), ".zam", "observer");
+function getUiObserverDir() {
+  return process.env.ZAM_OBSERVER_DIR || DEFAULT_UI_OBSERVER_DIR;
+}
+function getUiObservationPath(sessionId) {
+  if (!/^[A-Za-z0-9_-]+$/.test(sessionId)) {
+    throw new Error(`Invalid observer session ID: ${sessionId}`);
+  }
+  return join5(getUiObserverDir(), `${sessionId}.reports.jsonl`);
+}
+function ensureUiObserverDir() {
+  const dir = getUiObserverDir();
+  if (!existsSync5(dir)) {
+    mkdirSync4(dir, { recursive: true, mode: 448 });
+  }
+}
+function uiObservationLogExists(sessionId) {
+  return existsSync5(getUiObservationPath(sessionId));
+}
+function readUiObservationLog(sessionId) {
+  const path = getUiObservationPath(sessionId);
+  if (!existsSync5(path)) return [];
+  return parseUiObservationLog(readFileSync5(path, "utf8"));
+}
+function appendUiObservationReport(report) {
+  if (!isUiObservationReport(report)) {
+    throw new Error("Invalid UI observation report");
+  }
+  ensureUiObserverDir();
+  appendFileSync2(
+    getUiObservationPath(report.sessionId),
+    `${JSON.stringify(report)}
+`,
+    { encoding: "utf8", mode: 384 }
+  );
+}
+
+// src/kernel/observation/observer-sidecar-policy.ts
+var SIDECAR_POLICY_FILE = "policy.json";
+function toSidecarPrivacyPolicy(policy) {
+  return {
+    allowProcesses: [...policy.allowlist],
+    denyProcesses: [...policy.denylist],
+    denyTitleMarkers: [...policy.denylist]
+  };
+}
+async function syncObserverSidecarPolicy(db, dir = getUiObserverDir()) {
+  const policy = toSidecarPrivacyPolicy(await resolveObserverPolicy(db));
+  mkdirSync5(dir, { recursive: true, mode: 448 });
+  const path = join6(dir, SIDECAR_POLICY_FILE);
+  writeFileSync3(path, `${JSON.stringify(policy, null, 2)}
+`, {
+    encoding: "utf8",
+    mode: 384
+  });
+  return { path, policy };
+}
+
 // src/kernel/observation/session-synthesis.ts
 import { ulid as ulid7 } from "ulid";
 
@@ -2316,184 +2765,44 @@ async function cascadeBlock(db, userId, tokenSlug) {
         const now = (/* @__PURE__ */ new Date()).toISOString();
         await db.prepare(
           "UPDATE cards SET blocked = 0, due_at = ? WHERE token_id = ? AND user_id = ?"
-        ).run(now, prereq.requires_id, userId);
-      }
-    }
-    surfaced.push({
-      slug: prereq.slug,
-      concept: prereq.concept,
-      bloomLevel: prereq.bloom_level
-    });
-  }
-  return {
-    blockedSlug: tokenSlug,
-    prerequisites: surfaced
-  };
-}
-async function unblockReady(db, userId) {
-  const blockedCards = await db.prepare(
-    `SELECT c.token_id, t.slug, t.concept
-       FROM cards c
-       JOIN tokens t ON t.id = c.token_id
-       WHERE c.user_id = ? AND c.blocked = 1`
-  ).all(userId);
-  const unblocked = [];
-  for (const card of blockedCards) {
-    const totalPrereqs = await db.prepare("SELECT COUNT(*) as n FROM prerequisites WHERE token_id = ?").get(card.token_id);
-    const metPrereqs = await db.prepare(
-      `SELECT COUNT(*) as n FROM cards c
-         JOIN prerequisites p ON p.requires_id = c.token_id
-         WHERE p.token_id = ? AND c.user_id = ? AND c.reps >= 1 AND c.blocked = 0`
-    ).get(card.token_id, userId);
-    if (totalPrereqs.n === 0 || metPrereqs.n === totalPrereqs.n) {
-      const now = (/* @__PURE__ */ new Date()).toISOString();
-      await db.prepare(
-        "UPDATE cards SET blocked = 0, due_at = ? WHERE token_id = ? AND user_id = ?"
-      ).run(now, card.token_id, userId);
-      unblocked.push({ slug: card.slug, concept: card.concept });
-    }
-  }
-  return { unblocked };
-}
-
-// src/kernel/observation/ui-observer-io.ts
-import { appendFileSync as appendFileSync2, existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync5 } from "fs";
-import { homedir as homedir4 } from "os";
-import { join as join5 } from "path";
-
-// src/kernel/observation/ui-observer.ts
-var UI_OBSERVATION_PROTOCOL_VERSION = 1;
-var OBSERVATION_KINDS = /* @__PURE__ */ new Set([
-  "progress",
-  "step-completed",
-  "error",
-  "help-seeking",
-  "uncertain",
-  "privacy-pause",
-  "heartbeat"
-]);
-var ACTION_TYPES = /* @__PURE__ */ new Set([
-  "click",
-  "shortcut",
-  "typing",
-  "scroll",
-  "window-change"
-]);
-var EVIDENCE_TYPES = /* @__PURE__ */ new Set([
-  "uia",
-  "keyframe",
-  "clip",
-  "window"
-]);
-function isUiObservationReport(value) {
-  if (!isRecord(value)) return false;
-  if (value.version !== UI_OBSERVATION_PROTOCOL_VERSION) return false;
-  if (!isNonEmptyString(value.sessionId)) return false;
-  if (!isNonNegativeInteger(value.sequence)) return false;
-  if (!isNonEmptyString(value.observedFrom)) return false;
-  if (!isNonEmptyString(value.observedTo)) return false;
-  if (typeof value.kind !== "string" || !OBSERVATION_KINDS.has(value.kind)) {
-    return false;
-  }
-  if (!isApplication(value.application)) return false;
-  if (!isNonEmptyString(value.summary)) return false;
-  if (!Array.isArray(value.actions) || !value.actions.every(isObservedAction)) {
-    return false;
-  }
-  if (!Array.isArray(value.evidence) || !value.evidence.every(isEvidenceRef)) {
-    return false;
-  }
-  if (!Array.isArray(value.candidateTokens) || !value.candidateTokens.every(isCandidateToken)) {
-    return false;
-  }
-  return isConfidence(value.confidence);
-}
-function parseUiObservationLog(jsonl) {
-  const reports = [];
-  for (const line of jsonl.split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    try {
-      const value = JSON.parse(trimmed);
-      if (isUiObservationReport(value)) {
-        reports.push(value);
-      }
-    } catch {
-    }
-  }
-  return reports.sort((left, right) => left.sequence - right.sequence);
-}
-function isApplication(value) {
-  if (!isRecord(value) || !isNonEmptyString(value.processName)) return false;
-  if (value.processId !== void 0 && !isNonNegativeInteger(value.processId)) {
-    return false;
-  }
-  return value.windowTitle === void 0 || typeof value.windowTitle === "string";
-}
-function isObservedAction(value) {
-  if (!isRecord(value) || typeof value.type !== "string") return false;
-  if (!ACTION_TYPES.has(value.type)) return false;
-  if (value.target !== void 0 && typeof value.target !== "string") {
-    return false;
-  }
-  return value.result === void 0 || typeof value.result === "string";
-}
-function isEvidenceRef(value) {
-  if (!isRecord(value) || typeof value.type !== "string") return false;
-  return EVIDENCE_TYPES.has(value.type) && isNonEmptyString(value.ref) && typeof value.redacted === "boolean";
-}
-function isCandidateToken(value) {
-  return isRecord(value) && isNonEmptyString(value.slug) && isConfidence(value.confidence) && isNonEmptyString(value.rationale);
-}
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function isNonEmptyString(value) {
-  return typeof value === "string" && value.trim().length > 0;
-}
-function isNonNegativeInteger(value) {
-  return Number.isInteger(value) && Number(value) >= 0;
-}
-function isConfidence(value) {
-  return typeof value === "number" && value >= 0 && value <= 1;
-}
-
-// src/kernel/observation/ui-observer-io.ts
-var DEFAULT_UI_OBSERVER_DIR = join5(homedir4(), ".zam", "observer");
-function getUiObserverDir() {
-  return process.env.ZAM_OBSERVER_DIR || DEFAULT_UI_OBSERVER_DIR;
-}
-function getUiObservationPath(sessionId) {
-  if (!/^[A-Za-z0-9_-]+$/.test(sessionId)) {
-    throw new Error(`Invalid observer session ID: ${sessionId}`);
-  }
-  return join5(getUiObserverDir(), `${sessionId}.reports.jsonl`);
-}
-function ensureUiObserverDir() {
-  const dir = getUiObserverDir();
-  if (!existsSync5(dir)) {
-    mkdirSync4(dir, { recursive: true, mode: 448 });
+        ).run(now, prereq.requires_id, userId);
+      }
+    }
+    surfaced.push({
+      slug: prereq.slug,
+      concept: prereq.concept,
+      bloomLevel: prereq.bloom_level
+    });
   }
+  return {
+    blockedSlug: tokenSlug,
+    prerequisites: surfaced
+  };
 }
-function uiObservationLogExists(sessionId) {
-  return existsSync5(getUiObservationPath(sessionId));
-}
-function readUiObservationLog(sessionId) {
-  const path = getUiObservationPath(sessionId);
-  if (!existsSync5(path)) return [];
-  return parseUiObservationLog(readFileSync5(path, "utf8"));
-}
-function appendUiObservationReport(report) {
-  if (!isUiObservationReport(report)) {
-    throw new Error("Invalid UI observation report");
+async function unblockReady(db, userId) {
+  const blockedCards = await db.prepare(
+    `SELECT c.token_id, t.slug, t.concept
+       FROM cards c
+       JOIN tokens t ON t.id = c.token_id
+       WHERE c.user_id = ? AND c.blocked = 1`
+  ).all(userId);
+  const unblocked = [];
+  for (const card of blockedCards) {
+    const totalPrereqs = await db.prepare("SELECT COUNT(*) as n FROM prerequisites WHERE token_id = ?").get(card.token_id);
+    const metPrereqs = await db.prepare(
+      `SELECT COUNT(*) as n FROM cards c
+         JOIN prerequisites p ON p.requires_id = c.token_id
+         WHERE p.token_id = ? AND c.user_id = ? AND c.reps >= 1 AND c.blocked = 0`
+    ).get(card.token_id, userId);
+    if (totalPrereqs.n === 0 || metPrereqs.n === totalPrereqs.n) {
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      await db.prepare(
+        "UPDATE cards SET blocked = 0, due_at = ? WHERE token_id = ? AND user_id = ?"
+      ).run(now, card.token_id, userId);
+      unblocked.push({ slug: card.slug, concept: card.concept });
+    }
   }
-  ensureUiObserverDir();
-  appendFileSync2(
-    getUiObservationPath(report.sessionId),
-    `${JSON.stringify(report)}
-`,
-    { encoding: "utf8", mode: 384 }
-  );
+  return { unblocked };
 }
 
 // src/kernel/observation/ui-observer-synthesis.ts
@@ -3300,7 +3609,7 @@ function generatePrompt(input8) {
 
 // src/kernel/recall/reference-resolver.ts
 import { existsSync as existsSync6, readFileSync as readFileSync6 } from "fs";
-import { dirname as dirname3, join as join6, resolve } from "path";
+import { dirname as dirname3, join as join7, resolve } from "path";
 var DEFAULT_REVIEW_CONTEXT_MAX_CHARS = 6e3;
 function htmlToText(html) {
   let content = html;
@@ -3361,8 +3670,8 @@ async function resolveReference(sourceLink) {
       const filePath = anchorIndex2 !== -1 ? fullPathWithAnchor.slice(0, anchorIndex2) : fullPathWithAnchor;
       const anchor2 = anchorIndex2 !== -1 ? fullPathWithAnchor.slice(anchorIndex2) : "";
       const parentDir = dirname3(process.cwd());
-      const localRepoPath = join6(parentDir, repo);
-      const localFilePath = join6(localRepoPath, filePath);
+      const localRepoPath = join7(parentDir, repo);
+      const localFilePath = join7(localRepoPath, filePath);
       if (existsSync6(localFilePath)) {
         try {
           let fileContent = readFileSync6(localFilePath, "utf-8");
@@ -3676,12 +3985,12 @@ import {
   appendFileSync as appendFileSync3,
   copyFileSync,
   existsSync as existsSync7,
-  mkdirSync as mkdirSync5,
+  mkdirSync as mkdirSync6,
   readFileSync as readFileSync7,
-  writeFileSync as writeFileSync3
+  writeFileSync as writeFileSync4
 } from "fs";
 import { homedir as homedir5 } from "os";
-import { join as join7 } from "path";
+import { join as join8 } from "path";
 import { fileURLToPath } from "url";
 var HOME = homedir5();
 function getPackageSkillPath(agent = "default") {
@@ -3689,15 +3998,15 @@ function getPackageSkillPath(agent = "default") {
     fileURLToPath(new URL("../../..", import.meta.url)),
     fileURLToPath(new URL("../..", import.meta.url)),
     fileURLToPath(new URL("..", import.meta.url))
-  ].find((candidate) => existsSync7(join7(candidate, "package.json"))) ?? "";
+  ].find((candidate) => existsSync7(join8(candidate, "package.json"))) ?? "";
   if (!packageRoot2) return "";
   if (agent === "codex") {
-    const codexPath = join7(packageRoot2, ".agents", "skills", "zam", "SKILL.md");
+    const codexPath = join8(packageRoot2, ".agents", "skills", "zam", "SKILL.md");
     if (existsSync7(codexPath)) return codexPath;
     return "";
   }
   if (agent === "claude") {
-    const claudePath = join7(
+    const claudePath = join8(
       packageRoot2,
       ".claude",
       "skills",
@@ -3707,9 +4016,9 @@ function getPackageSkillPath(agent = "default") {
     if (existsSync7(claudePath)) return claudePath;
     return "";
   }
-  let path = join7(packageRoot2, ".agent", "skills", "zam", "SKILL.md");
+  let path = join8(packageRoot2, ".agent", "skills", "zam", "SKILL.md");
   if (existsSync7(path)) return path;
-  path = join7(packageRoot2, ".claude", "skills", "zam", "SKILL.md");
+  path = join8(packageRoot2, ".claude", "skills", "zam", "SKILL.md");
   if (existsSync7(path)) return path;
   return "";
 }
@@ -3722,16 +4031,16 @@ function distributeGlobalSkills(home = HOME) {
     console.warn("Could not find ZAM source SKILL.md in the package folder.");
     return results;
   }
-  const claudeSkillsDir = join7(home, ".claude", "skills", "zam");
+  const claudeSkillsDir = join8(home, ".claude", "skills", "zam");
   try {
     if (!claudeSourceSkill) {
       throw new Error("Claude skill source not found");
     }
-    mkdirSync5(claudeSkillsDir, { recursive: true });
-    copyFileSync(claudeSourceSkill, join7(claudeSkillsDir, "SKILL.md"));
+    mkdirSync6(claudeSkillsDir, { recursive: true });
+    copyFileSync(claudeSourceSkill, join8(claudeSkillsDir, "SKILL.md"));
     results.push({
       name: "Claude Code Global",
-      path: join7(claudeSkillsDir, "SKILL.md"),
+      path: join8(claudeSkillsDir, "SKILL.md"),
       success: true
     });
   } catch (_err) {
@@ -3741,13 +4050,13 @@ function distributeGlobalSkills(home = HOME) {
       success: false
     });
   }
-  const geminiSkillsDir = join7(home, ".gemini", "skills", "zam");
+  const geminiSkillsDir = join8(home, ".gemini", "skills", "zam");
   try {
-    mkdirSync5(geminiSkillsDir, { recursive: true });
-    copyFileSync(sourceSkill, join7(geminiSkillsDir, "SKILL.md"));
+    mkdirSync6(geminiSkillsDir, { recursive: true });
+    copyFileSync(sourceSkill, join8(geminiSkillsDir, "SKILL.md"));
     results.push({
       name: "Gemini CLI Global",
-      path: join7(geminiSkillsDir, "SKILL.md"),
+      path: join8(geminiSkillsDir, "SKILL.md"),
       success: true
     });
   } catch (_err) {
@@ -3757,16 +4066,16 @@ function distributeGlobalSkills(home = HOME) {
       success: false
     });
   }
-  const codexSkillsDir = join7(home, ".agents", "skills", "zam");
+  const codexSkillsDir = join8(home, ".agents", "skills", "zam");
   try {
     if (!codexSourceSkill) {
       throw new Error("Codex skill source not found");
     }
-    mkdirSync5(codexSkillsDir, { recursive: true });
-    copyFileSync(codexSourceSkill, join7(codexSkillsDir, "SKILL.md"));
+    mkdirSync6(codexSkillsDir, { recursive: true });
+    copyFileSync(codexSourceSkill, join8(codexSkillsDir, "SKILL.md"));
     results.push({
       name: "Codex Global",
-      path: join7(codexSkillsDir, "SKILL.md"),
+      path: join8(codexSkillsDir, "SKILL.md"),
       success: true
     });
   } catch (_err) {
@@ -3776,13 +4085,13 @@ function distributeGlobalSkills(home = HOME) {
       success: false
     });
   }
-  const gooseSkillsDir = join7(home, ".goose", "skills", "zam");
+  const gooseSkillsDir = join8(home, ".goose", "skills", "zam");
   try {
-    mkdirSync5(gooseSkillsDir, { recursive: true });
-    copyFileSync(sourceSkill, join7(gooseSkillsDir, "SKILL.md"));
+    mkdirSync6(gooseSkillsDir, { recursive: true });
+    copyFileSync(sourceSkill, join8(gooseSkillsDir, "SKILL.md"));
     results.push({
       name: "Goose Global",
-      path: join7(gooseSkillsDir, "SKILL.md"),
+      path: join8(gooseSkillsDir, "SKILL.md"),
       success: true
     });
   } catch (_err) {
@@ -3831,7 +4140,7 @@ function installHook(file, hook, oldHook) {
       return { success: true, alreadyHooked: true };
     }
     if (content.includes(oldHook.trim())) {
-      writeFileSync3(file, content.replace(oldHook.trim(), hook.trim()), "utf8");
+      writeFileSync4(file, content.replace(oldHook.trim(), hook.trim()), "utf8");
     } else {
       appendFileSync3(file, hook);
     }
@@ -3842,24 +4151,24 @@ function installHook(file, hook, oldHook) {
 }
 function injectShellHooks(home = HOME) {
   const results = [];
-  const zshrc = join7(home, ".zshrc");
+  const zshrc = join8(home, ".zshrc");
   if (existsSync7(zshrc)) {
     const status = installHook(zshrc, posixHook("zsh"), POSIX_OLD_HOOK);
     results.push({ shell: "zsh", file: zshrc, ...status });
   }
-  const bashrc = join7(home, ".bashrc");
+  const bashrc = join8(home, ".bashrc");
   if (existsSync7(bashrc)) {
     const status = installHook(bashrc, posixHook("bash"), POSIX_OLD_HOOK);
     results.push({ shell: "bash", file: bashrc, ...status });
   }
   const pwshDirs = [
-    join7(home, "Documents", "PowerShell"),
-    join7(home, "Documents", "WindowsPowerShell")
+    join8(home, "Documents", "PowerShell"),
+    join8(home, "Documents", "WindowsPowerShell")
   ];
   for (const dir of pwshDirs) {
-    const profileFile = join7(dir, "Microsoft.PowerShell_profile.ps1");
+    const profileFile = join8(dir, "Microsoft.PowerShell_profile.ps1");
     try {
-      mkdirSync5(dir, { recursive: true });
+      mkdirSync6(dir, { recursive: true });
       const status = installHook(
         profileFile,
         POWERSHELL_HOOK,
@@ -4091,10 +4400,10 @@ function t(locale, key, params = {}) {
 }
 
 // src/kernel/system/install-config.ts
-import { existsSync as existsSync8, mkdirSync as mkdirSync6, readFileSync as readFileSync8, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync8, mkdirSync as mkdirSync7, readFileSync as readFileSync8, writeFileSync as writeFileSync5 } from "fs";
 import { homedir as homedir6 } from "os";
-import { dirname as dirname4, join as join8 } from "path";
-var DEFAULT_CONFIG_PATH = join8(homedir6(), ".zam", "config.json");
+import { dirname as dirname4, join as join9 } from "path";
+var DEFAULT_CONFIG_PATH = join9(homedir6(), ".zam", "config.json");
 function loadInstallConfig(path = DEFAULT_CONFIG_PATH) {
   if (!existsSync8(path)) return {};
   try {
@@ -4105,8 +4414,8 @@ function loadInstallConfig(path = DEFAULT_CONFIG_PATH) {
 }
 function saveInstallConfig(config, path = DEFAULT_CONFIG_PATH) {
   const dir = dirname4(path);
-  if (!existsSync8(dir)) mkdirSync6(dir, { recursive: true });
-  writeFileSync4(path, `${JSON.stringify(config, null, 2)}
+  if (!existsSync8(dir)) mkdirSync7(dir, { recursive: true });
+  writeFileSync5(path, `${JSON.stringify(config, null, 2)}
 `, "utf-8");
 }
 function getInstallMode(path = DEFAULT_CONFIG_PATH) {
@@ -4139,7 +4448,7 @@ function detectSyncProvider(dir) {
 import { execFileSync, execSync } from "child_process";
 import { existsSync as existsSync9 } from "fs";
 import { homedir as homedir7 } from "os";
-import { join as join9 } from "path";
+import { join as join10 } from "path";
 function hasCommand(cmd) {
   try {
     const checkCmd2 = process.platform === "win32" ? `where ${cmd}` : `which ${cmd}`;
@@ -4184,7 +4493,7 @@ function installOllama() {
   const isMac = process.platform === "darwin";
   const isWin = process.platform === "win32";
   const hasOllama = hasCommand("ollama") || isMac && existsSync9("/Applications/Ollama.app") || isWin && existsSync9(
-    join9(homedir7(), "AppData", "Local", "Programs", "Ollama", "ollama.exe")
+    join10(homedir7(), "AppData", "Local", "Programs", "Ollama", "ollama.exe")
   );
   if (hasOllama) {
     return { success: true, message: "Ollama is already installed." };
@@ -4244,7 +4553,7 @@ function installOllama() {
 function resolveOllamaCommand() {
   if (hasCommand("ollama")) return "ollama";
   const candidates = process.platform === "win32" ? [
-    join9(
+    join10(
       homedir7(),
       "AppData",
       "Local",
@@ -4538,6 +4847,37 @@ function decideUpdate(input8) {
       };
   }
 }
+function planUpdate(decision) {
+  if (!decision.updateAvailable) return [];
+  switch (decision.channel) {
+    case "developer":
+      return [
+        { kind: "git-pull", label: "Pull the latest source" },
+        { kind: "npm-install", label: "Install dependencies" },
+        { kind: "npm-build", label: "Rebuild the CLI" },
+        {
+          kind: "distribute-skills",
+          label: "Refresh skill files (zam setup --force)"
+        }
+      ];
+    case "winget":
+    case "homebrew":
+      return [
+        {
+          kind: "run-command",
+          label: `Update via ${decision.channel}`,
+          command: decision.command
+        }
+      ];
+    case "direct":
+      return [
+        {
+          kind: "self-update",
+          label: "Apply the signed update via the desktop app"
+        }
+      ];
+  }
+}
 
 // src/cli/commands/agent.ts
 var C = {
@@ -4550,7 +4890,7 @@ var C = {
 };
 var SUPPORTED_AGENTS = ["opencode"];
 function agentsMdPresent(cwd = process.cwd()) {
-  return existsSync11(join10(cwd, "AGENTS.md"));
+  return existsSync11(join11(cwd, "AGENTS.md"));
 }
 function printStatus() {
   const installed = hasCommand("opencode");
@@ -4591,9 +4931,11 @@ var statusCmd = new Command("status").description("Show whether the agent is ins
 var agentCommand = new Command("agent").description("Provision and inspect the agent that drives ZAM sessions").addCommand(installCmd).addCommand(statusCmd).action(printStatus);
 
 // src/cli/commands/bridge.ts
-import { readdirSync as readdirSync2 } from "fs";
-import { homedir as homedir8 } from "os";
-import { join as join11 } from "path";
+import { execFileSync as execFileSync2 } from "child_process";
+import { randomBytes } from "crypto";
+import { readdirSync as readdirSync2, readFileSync as readFileSync10, rmSync as rmSync2 } from "fs";
+import { homedir as homedir8, tmpdir } from "os";
+import { join as join12 } from "path";
 import { Command as Command2 } from "commander";
 
 // src/cli/llm/client.ts
@@ -4956,8 +5298,8 @@ async function startLocalRunner(url, model, locale) {
       process.stdout.write("\n");
       console.log(`\x1B[33m${t(locale, "wait_warning")}\x1B[0m`);
       console.log(`\x1B[2m${t(locale, "wait_info")}\x1B[0m`);
-      const { confirm: confirm4 } = await import("@inquirer/prompts");
-      const keepWaiting = await confirm4({
+      const { confirm: confirm5 } = await import("@inquirer/prompts");
+      const keepWaiting = await confirm5({
         message: t(locale, "keep_waiting_llm"),
         default: true
       }).catch(() => false);
@@ -5101,8 +5443,8 @@ async function fetchWithInteractiveTimeout(url, options = {}) {
       }
       console.log(`
 \x1B[33m${t(locale, "local_ai_working")}\x1B[0m`);
-      const { confirm: confirm4 } = await import("@inquirer/prompts");
-      const keepWaiting = await confirm4({
+      const { confirm: confirm5 } = await import("@inquirer/prompts");
+      const keepWaiting = await confirm5({
         message: t(locale, "keep_waiting"),
         default: true
       }).catch(() => false);
@@ -5730,13 +6072,15 @@ bridgeCommand.command("start-session").description("Start a ZAM learning session
       task: opts.task,
       execution_context: context
     });
+    const observerPolicyHint = context === "ui" && !await isObserverPolicyConfigured(db) ? OBSERVER_POLICY_UNSET_HINT : void 0;
     jsonOut2({
       id: session.id,
       userId: session.user_id,
       task: session.task,
       executionContext: session.execution_context,
       startedAt: session.started_at,
-      completedAt: session.completed_at
+      completedAt: session.completed_at,
+      ...observerPolicyHint ? { observerPolicyHint } : {}
     });
   });
 });
@@ -5859,7 +6203,8 @@ bridgeCommand.command("add-token").description("Create a token + card from JSON
       bloom_level: data?.bloom_level ?? 1,
       context: data?.context,
       symbiosis_mode: data?.symbiosis_mode,
-      source_link: data?.source_link ?? null
+      source_link: data?.source_link ?? null,
+      question: data?.question ?? null
     });
     const card = await ensureCard(db, token.id, userId);
     jsonOut2({
@@ -5894,7 +6239,7 @@ bridgeCommand.command("discover-skills").description(
   "20"
 ).action(async (opts) => {
   try {
-    const monitorDir = join11(homedir8(), ".zam", "monitor");
+    const monitorDir = join12(homedir8(), ".zam", "monitor");
     let files;
     try {
       files = readdirSync2(monitorDir).filter((f) => f.endsWith(".jsonl"));
@@ -5907,7 +6252,7 @@ bridgeCommand.command("discover-skills").description(
       return;
     }
     const limit = Number(opts.limit);
-    const sorted = files.map((f) => ({ name: f, path: join11(monitorDir, f) })).sort((a, b) => b.name.localeCompare(a.name)).slice(0, limit);
+    const sorted = files.map((f) => ({ name: f, path: join12(monitorDir, f) })).sort((a, b) => b.name.localeCompare(a.name)).slice(0, limit);
     const sessionCommands = /* @__PURE__ */ new Map();
     for (const file of sorted) {
       const sessionId = file.name.replace(".jsonl", "");
@@ -5917,104 +6262,566 @@ bridgeCommand.command("discover-skills").description(
         sessionCommands.set(sessionId, commands);
       }
     }
-    if (sessionCommands.size === 0) {
-      jsonOut2({ proposals: [], message: "No command data in monitor logs." });
-      return;
-    }
-    let existingSkillSlugs = [];
-    let db;
-    try {
-      db = await openDatabase();
-      existingSkillSlugs = (await listAgentSkills(db)).map((s) => s.slug);
-    } catch {
-    } finally {
-      await db?.close();
-    }
-    const proposals = discoverSkills(sessionCommands, {
-      minSessions: Number(opts.minSessions),
-      existingSkillSlugs
-    });
-    jsonOut2({
-      sessionsAnalyzed: sessionCommands.size,
-      proposals
-    });
-  } catch (err) {
-    jsonError(err.message);
+    if (sessionCommands.size === 0) {
+      jsonOut2({ proposals: [], message: "No command data in monitor logs." });
+      return;
+    }
+    let existingSkillSlugs = [];
+    let db;
+    try {
+      db = await openDatabase();
+      existingSkillSlugs = (await listAgentSkills(db)).map((s) => s.slug);
+    } catch {
+    } finally {
+      await db?.close();
+    }
+    const proposals = discoverSkills(sessionCommands, {
+      minSessions: Number(opts.minSessions),
+      existingSkillSlugs
+    });
+    jsonOut2({
+      sessionsAnalyzed: sessionCommands.size,
+      proposals
+    });
+  } catch (err) {
+    jsonError(err.message);
+  }
+});
+bridgeCommand.command("observe-ui-watch").description(
+  "Poll live UI observer watch reports for a ZAM learning session (JSON)"
+).requiredOption(
+  "--session <id>",
+  "ZAM session ID (also the observer log key)"
+).option("--after <n>", "Only return observations after this sequence").option("--limit <n>", "Maximum observations to return", "100").action(async (opts) => {
+  await withDb2(async (db) => {
+    const session = await db.prepare("SELECT id, execution_context FROM sessions WHERE id = ?").get(opts.session);
+    if (!session) {
+      jsonError(`Session not found: ${opts.session}`);
+    }
+    const after = opts.after === void 0 ? void 0 : parseNonNegativeIntegerOption("after", opts.after);
+    const limit = parseNonNegativeIntegerOption("limit", opts.limit);
+    const observations = readUiObservationLog(opts.session).filter((report) => after === void 0 || report.sequence > after).slice(0, limit);
+    const last = observations[observations.length - 1];
+    jsonOut2({
+      sessionId: opts.session,
+      executionContext: session.execution_context,
+      observationSource: "ui",
+      logExists: uiObservationLogExists(opts.session),
+      after: after ?? null,
+      count: observations.length,
+      nextSequence: last?.sequence ?? after ?? null,
+      observations
+    });
+  });
+});
+bridgeCommand.command("get-observations").description("Read UI observer reports for a session (JSON)").requiredOption("--session <id>", "Observer session ID").option("--after <n>", "Only return observations after this sequence").option("--limit <n>", "Maximum observations to return", "100").action((opts) => {
+  try {
+    const after = opts.after === void 0 ? void 0 : parseNonNegativeIntegerOption("after", opts.after);
+    const limit = parseNonNegativeIntegerOption("limit", opts.limit);
+    const observations = readUiObservationLog(opts.session).filter((report) => after === void 0 || report.sequence > after).slice(0, limit);
+    const last = observations[observations.length - 1];
+    jsonOut2({
+      sessionId: opts.session,
+      after: after ?? null,
+      count: observations.length,
+      nextSequence: last?.sequence ?? after ?? null,
+      observations
+    });
+  } catch (err) {
+    jsonError(err.message);
+  }
+});
+bridgeCommand.command("observe-ui-snapshot").description(
+  "Analyze a captured UI snapshot with the configured vision LLM (JSON)"
+).requiredOption("--session <id>", "Observer session ID").requiredOption("--sequence <n>", "Monotonic observation sequence number").requiredOption("--image <path>", "PNG snapshot path").requiredOption("--observed-from <iso>", "Observation window start time").requiredOption("--observed-to <iso>", "Observation window end time").requiredOption("--process-name <name>", "Observed application process name").option("--process-id <n>", "Observed application process ID").option("--window-title <title>", "Observed window title").option("--evidence-ref <ref>", "Evidence reference to put in the report").option("--model <model>", "Override configured LLM model for this request").option("--max-tokens <n>", "Model response token budget").option("--timeout <ms>", "Hard request timeout in milliseconds").option("--redacted", "Mark the snapshot evidence as redacted").option("--write-log", "Append the generated report to the session JSONL").action(async (opts) => {
+  const sequence = parseNonNegativeIntegerOption("sequence", opts.sequence);
+  const processId = opts.processId === void 0 ? void 0 : parseNonNegativeIntegerOption("process-id", opts.processId);
+  const maxTokens = opts.maxTokens === void 0 ? void 0 : parseNonNegativeIntegerOption("max-tokens", opts.maxTokens);
+  const hardTimeoutMs = opts.timeout === void 0 ? void 0 : parseNonNegativeIntegerOption("timeout", opts.timeout);
+  await withDb2(async (db) => {
+    const report = await observeUiSnapshotViaLLM(db, {
+      sessionId: opts.session,
+      sequence,
+      observedFrom: opts.observedFrom,
+      observedTo: opts.observedTo,
+      imagePath: opts.image,
+      application: {
+        processName: opts.processName,
+        processId,
+        windowTitle: opts.windowTitle
+      },
+      evidenceRef: opts.evidenceRef,
+      redacted: opts.redacted === true,
+      model: opts.model,
+      maxTokens,
+      hardTimeoutMs
+    });
+    if (opts.writeLog === true) {
+      appendUiObservationReport(report);
+    }
+    jsonOut2(report);
+  });
+});
+function resolveWindowsPowerShell() {
+  try {
+    execFileSync2("where.exe", ["pwsh.exe"], { stdio: "ignore" });
+    return "pwsh";
+  } catch {
+    return "powershell";
+  }
+}
+function captureScreenshot(outputPath, hwnd, processName) {
+  const platform = process.platform;
+  if (hwnd && !/^(0x)?[0-9a-fA-F]+$/.test(hwnd)) {
+    throw new Error(`Invalid HWND format: ${hwnd}`);
+  }
+  if (processName && !/^[a-zA-Z0-9\-_.]+$/.test(processName)) {
+    throw new Error(`Invalid process name format: ${processName}`);
+  }
+  if (platform === "win32") {
+    const stdout = execFileSync2(
+      resolveWindowsPowerShell(),
+      [
+        "-NoProfile",
+        "-Command",
+        `
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+
+$code = @'
+using System;
+using System.Runtime.InteropServices;
+
+public class Win32 {
+    public delegate bool EnumWindowsProc(IntPtr hWnd, IntPtr lParam);
+
+    [DllImport("user32.dll")]
+    public static extern bool SetProcessDPIAware();
+
+    [DllImport("user32.dll")]
+    public static extern bool SetProcessDpiAwarenessContext(IntPtr dpiContext);
+
+    [DllImport("user32.dll")]
+    public static extern bool GetWindowRect(IntPtr hWnd, out RECT rect);
+
+    [DllImport("user32.dll")]
+    public static extern bool EnumWindows(EnumWindowsProc lpEnumFunc, IntPtr lParam);
+
+    [DllImport("user32.dll")]
+    public static extern bool EnumChildWindows(IntPtr hWnd, EnumWindowsProc lpEnumFunc, IntPtr lParam);
+
+    [DllImport("user32.dll")]
+    public static extern bool IsWindowVisible(IntPtr hWnd);
+
+    [DllImport("user32.dll", SetLastError=true)]
+    public static extern int GetWindowText(IntPtr hWnd, System.Text.StringBuilder lpString, int nMaxCount);
+
+    [DllImport("user32.dll", SetLastError=true)]
+    public static extern int GetWindowTextLength(IntPtr hWnd);
+
+    [DllImport("user32.dll")]
+    public static extern uint GetWindowThreadProcessId(IntPtr hWnd, out uint lpdwProcessId);
+
+    [DllImport("user32.dll")]
+    public static extern bool SetForegroundWindow(IntPtr hWnd);
+
+    [DllImport("user32.dll")]
+    public static extern bool ShowWindow(IntPtr hWnd, int nCmdShow);
+
+    [DllImport("user32.dll")]
+    public static extern bool IsIconic(IntPtr hWnd);
+
+    [DllImport("user32.dll")]
+    public static extern bool PrintWindow(IntPtr hWnd, IntPtr hdcBlt, uint nFlags);
+
+    [StructLayout(LayoutKind.Sequential)]
+    public struct RECT {
+        public int Left;
+        public int Top;
+        public int Right;
+        public int Bottom;
+    }
+}
+'@
+Add-Type -TypeDefinition $code
+
+try {
+    # DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2 = -4. Without this, Windows
+    # can return logical window bounds while PrintWindow renders physical
+    # pixels, causing high-DPI captures to crop the right/bottom edge.
+    [Win32]::SetProcessDpiAwarenessContext([IntPtr](-4)) | Out-Null
+} catch {
+    try { [Win32]::SetProcessDPIAware() | Out-Null } catch {}
+}
+
+function Get-WindowTitle([IntPtr]$hWnd) {
+    $length = [Win32]::GetWindowTextLength($hWnd)
+    $capacity = [Math]::Max(1, $length + 1)
+    $builder = New-Object System.Text.StringBuilder $capacity
+    [Win32]::GetWindowText($hWnd, $builder, $builder.Capacity) | Out-Null
+    $builder.ToString()
+}
+
+function Get-WindowProcess([IntPtr]$hWnd) {
+    [uint32]$processId = 0
+    [Win32]::GetWindowThreadProcessId($hWnd, [ref]$processId) | Out-Null
+    if ($processId -eq 0) { return $null }
+    Get-Process -Id $processId -ErrorAction SilentlyContinue
+}
+
+function Get-VisibleTopLevelWindows {
+    $script:windowCandidates = New-Object System.Collections.ArrayList
+    $callback = [Win32+EnumWindowsProc]{
+        param([IntPtr]$candidateHwnd, [IntPtr]$lParam)
+        if ([Win32]::IsWindowVisible($candidateHwnd)) {
+            $candidateRect = New-Object Win32+RECT
+            if ([Win32]::GetWindowRect($candidateHwnd, [ref]$candidateRect)) {
+                $candidateWidth = $candidateRect.Right - $candidateRect.Left
+                $candidateHeight = $candidateRect.Bottom - $candidateRect.Top
+                if ($candidateWidth -gt 0 -and $candidateHeight -gt 0) {
+                    [void]$script:windowCandidates.Add($candidateHwnd)
+                }
+            }
+        }
+        return $true
+    }
+    [Win32]::EnumWindows($callback, [IntPtr]::Zero) | Out-Null
+    $windows = $script:windowCandidates
+    Remove-Variable -Name windowCandidates -Scope Script -ErrorAction SilentlyContinue
+    $windows
+}
+
+function Find-TopLevelWindowByProcessName([string]$name) {
+    foreach ($candidateHwnd in Get-VisibleTopLevelWindows) {
+        $candidateProcess = Get-WindowProcess $candidateHwnd
+        if ($candidateProcess -and $candidateProcess.ProcessName -ieq $name) {
+            return [pscustomobject]@{
+                Hwnd = $candidateHwnd
+                MatchedBy = "process-top-level-window"
+            }
+        }
+
+        $script:desiredChildProcessName = $name
+        $script:foundChildProcessWindow = $false
+        $childCallback = [Win32+EnumWindowsProc]{
+            param([IntPtr]$childHwnd, [IntPtr]$lParam)
+            $childProcess = Get-WindowProcess $childHwnd
+            if ($childProcess -and $childProcess.ProcessName -ieq $script:desiredChildProcessName) {
+                $script:foundChildProcessWindow = $true
+                return $false
+            }
+            return $true
+        }
+        [Win32]::EnumChildWindows($candidateHwnd, $childCallback, [IntPtr]::Zero) | Out-Null
+        $foundChild = $script:foundChildProcessWindow
+        Remove-Variable -Name desiredChildProcessName -Scope Script -ErrorAction SilentlyContinue
+        Remove-Variable -Name foundChildProcessWindow -Scope Script -ErrorAction SilentlyContinue
+
+        if ($foundChild) {
+            return [pscustomobject]@{
+                Hwnd = $candidateHwnd
+                MatchedBy = "process-child-window"
+            }
+        }
+    }
+
+    return $null
+}
+
+function New-CaptureTarget([IntPtr]$hWnd, [string]$matchedBy) {
+    $target = [ordered]@{
+        requestedHwnd = if ($targetHwnd -ne '') { $targetHwnd } else { $null }
+        requestedProcessName = if ($processName -ne '') { $processName } else { $null }
+        matchedBy = $matchedBy
+        hwnd = $null
+        processId = $null
+        processName = $null
+        windowTitle = $null
+        bounds = $null
+    }
+
+    if ($hWnd -ne [IntPtr]::Zero) {
+        $target.hwnd = $hWnd.ToInt64()
+        $target.windowTitle = Get-WindowTitle $hWnd
+
+        $windowProcess = Get-WindowProcess $hWnd
+        if ($windowProcess) {
+            $target.processId = $windowProcess.Id
+            $target.processName = $windowProcess.ProcessName
+        }
+
+        $targetRect = New-Object Win32+RECT
+        if ([Win32]::GetWindowRect($hWnd, [ref]$targetRect)) {
+            $target.bounds = [ordered]@{
+                left = $targetRect.Left
+                top = $targetRect.Top
+                right = $targetRect.Right
+                bottom = $targetRect.Bottom
+                width = $targetRect.Right - $targetRect.Left
+                height = $targetRect.Bottom - $targetRect.Top
+            }
+        }
+    }
+
+    $target
+}
+
+function Write-CaptureResult([string]$method, [IntPtr]$hWnd, [string]$matchedBy) {
+    $result = [ordered]@{
+        method = $method
+        target = New-CaptureTarget $hWnd $matchedBy
+    }
+    Write-Output ("CAPTURE_RESULT:" + ($result | ConvertTo-Json -Compress -Depth 6))
+}
+
+$hwndVal = [IntPtr]::Zero
+$matchedBy = "fullscreen-fallback"
+$targetHwnd = '${hwnd || ""}'
+$processName = '${processName || ""}'
+
+if ($targetHwnd -ne '') {
+    if ($targetHwnd.StartsWith("0x")) {
+        $hwndVal = [IntPtr][Convert]::ToInt64($targetHwnd, 16)
+    } else {
+        $hwndVal = [IntPtr][Convert]::ToInt64($targetHwnd, 10)
+    }
+    $matchedBy = "hwnd"
+} elseif ($processName -ne '') {
+    $proc = Get-Process -Name $processName -ErrorAction SilentlyContinue | Where-Object {$_.MainWindowHandle -ne 0} | Select-Object -First 1
+    if ($proc) {
+        $hwndVal = $proc.MainWindowHandle
+        $matchedBy = "process-main-window"
+    } else {
+        $proc = Get-Process -Name $processName -ErrorAction SilentlyContinue | Select-Object -First 1
+        if ($proc) {
+            $hwndVal = $proc.MainWindowHandle
+            $matchedBy = "process-zero-main-window"
+        }
+    }
+
+    if ($hwndVal -eq [IntPtr]::Zero) {
+        $windowMatch = Find-TopLevelWindowByProcessName $processName
+        if ($windowMatch) {
+            $hwndVal = $windowMatch.Hwnd
+            $matchedBy = $windowMatch.MatchedBy
+        }
+    }
+}
+
+if ($hwndVal -ne [IntPtr]::Zero) {
+    if ([Win32]::IsIconic($hwndVal)) {
+        [Win32]::ShowWindow($hwndVal, 9) | Out-Null # SW_RESTORE = 9
+        Start-Sleep -Milliseconds 250
+    }
+
+    $rect = New-Object Win32+RECT
+    if ([Win32]::GetWindowRect($hwndVal, [ref]$rect)) {
+        $width = $rect.Right - $rect.Left
+        $height = $rect.Bottom - $rect.Top
+        if ($width -gt 0 -and $height -gt 0) {
+            $bitmap = New-Object System.Drawing.Bitmap($width, $height)
+            $graphics = [System.Drawing.Graphics]::FromImage($bitmap)
+            # PrintWindow renders the target window directly, regardless of
+            # z-order, so an occluded or background window is still captured
+            # correctly. SetForegroundWindow from a background process is
+            # blocked by Windows, so CopyFromScreen would grab whatever sits
+            # on top. PW_RENDERFULLCONTENT (0x2) handles modern/UWP windows.
+            $hdc = $graphics.GetHdc()
+            $printed = [Win32]::PrintWindow($hwndVal, $hdc, 2)
+            $graphics.ReleaseHdc($hdc)
+            $method = "printwindow"
+
+            # Black-frame guard: PrintWindow can return a near-black frame on
+            # some hardware-accelerated / DirectComposition surfaces. Sample a
+            # sparse grid; if it is essentially black, fall back to a foreground
+            # CopyFromScreen grab so the capture self-heals on those drivers.
+            $needFallback = -not $printed
+            if (-not $needFallback) {
+                $sum = 0.0
+                $cnt = 0
+                $stepX = [Math]::Max(1, [int]($width / 12))
+                $stepY = [Math]::Max(1, [int]($height / 12))
+                for ($sy = 0; $sy -lt $height; $sy += $stepY) {
+                    for ($sx = 0; $sx -lt $width; $sx += $stepX) {
+                        $px = $bitmap.GetPixel($sx, $sy)
+                        $sum += ($px.R + $px.G + $px.B) / 3.0
+                        $cnt++
+                    }
+                }
+                if ($cnt -gt 0 -and ($sum / $cnt) -lt 6) { $needFallback = $true }
+            }
+
+            if ($needFallback) {
+                [Win32]::SetForegroundWindow($hwndVal) | Out-Null
+                Start-Sleep -Milliseconds 250
+                $graphics.CopyFromScreen($rect.Left, $rect.Top, 0, 0, $bitmap.Size)
+                $method = "copyfromscreen"
+            }
+            $bitmap.Save('${outputPath.replace(/\\/g, "\\\\")}', [System.Drawing.Imaging.ImageFormat]::Png)
+            $graphics.Dispose()
+            $bitmap.Dispose()
+            Write-CaptureResult $method $hwndVal $matchedBy
+            exit 0
+        }
+    }
+}
+
+# Fallback: full primary screen
+$screen = [System.Windows.Forms.Screen]::PrimaryScreen.Bounds
+$bitmap = New-Object System.Drawing.Bitmap($screen.Width, $screen.Height)
+$graphics = [System.Drawing.Graphics]::FromImage($bitmap)
+$graphics.CopyFromScreen($screen.Location, [System.Drawing.Point]::Empty, $screen.Size)
+$bitmap.Save('${outputPath.replace(/\\/g, "\\\\")}', [System.Drawing.Imaging.ImageFormat]::Png)
+$graphics.Dispose()
+$bitmap.Dispose()
+Write-CaptureResult "fullscreen" $hwndVal $matchedBy
+        `.trim()
+      ],
+      { stdio: "pipe", encoding: "utf8" }
+    );
+    const resultMatch = /CAPTURE_RESULT:(\{.*\})/.exec(stdout ?? "");
+    if (resultMatch) {
+      const parsed = JSON.parse(resultMatch[1]);
+      return parsed;
+    }
+    const methodMatch = /CAPTURE_METHOD:(\w+)/.exec(stdout ?? "");
+    return {
+      method: methodMatch ? methodMatch[1] : "unknown",
+      target: null
+    };
+  } else if (platform === "darwin") {
+    if (hwnd) {
+      const parsedHwnd = hwnd.startsWith("0x") ? parseInt(hwnd, 16) : parseInt(hwnd, 10);
+      execFileSync2("screencapture", ["-l", String(parsedHwnd), outputPath], {
+        stdio: "pipe"
+      });
+      return { method: "screencapture-window", target: null };
+    } else if (processName) {
+      try {
+        const windowId = execFileSync2(
+          "osascript",
+          [
+            "-e",
+            `tell application "System Events" to get id of window 1 of process "${processName}"`
+          ],
+          { encoding: "utf8", stdio: ["pipe", "pipe", "ignore"] }
+        ).trim();
+        if (windowId && /^\d+$/.test(windowId)) {
+          execFileSync2("screencapture", ["-l", windowId, outputPath], {
+            stdio: "pipe"
+          });
+          return { method: "screencapture-window", target: null };
+        }
+      } catch {
+      }
+      execFileSync2("screencapture", ["-x", outputPath], { stdio: "pipe" });
+      return { method: "screencapture-full", target: null };
+    } else {
+      execFileSync2("screencapture", ["-x", outputPath], { stdio: "pipe" });
+      return { method: "screencapture-full", target: null };
+    }
+  } else {
+    throw new Error(
+      `Screen capture not supported on platform: ${platform}. Use zam-observer or provide --image.`
+    );
   }
-});
-bridgeCommand.command("observe-ui-watch").description(
-  "Poll live UI observer watch reports for a ZAM learning session (JSON)"
-).requiredOption(
-  "--session <id>",
-  "ZAM session ID (also the observer log key)"
-).option("--after <n>", "Only return observations after this sequence").option("--limit <n>", "Maximum observations to return", "100").action(async (opts) => {
+}
+bridgeCommand.command("capture-ui").description("Capture a screenshot for agent-side vision analysis (JSON)").option("--session <id>", "ZAM session ID (for metadata)").option("--output <path>", "PNG output path (defaults to temp file)").option("--image <path>", "Skip capture; return an existing image instead").option("--hwnd <hwnd>", "Window handle (decimal or hex) to capture").option("--process-name <name>", "Process name to capture").action(async (opts) => {
   await withDb2(async (db) => {
-    const session = await db.prepare("SELECT id, execution_context FROM sessions WHERE id = ?").get(opts.session);
-    if (!session) {
-      jsonError(`Session not found: ${opts.session}`);
+    const policy = await resolveObserverPolicy(db);
+    const permission = {
+      scope: policy.scope,
+      consent: policy.consent,
+      retention: policy.retention
+    };
+    const isProvided = Boolean(opts.image);
+    if (!isProvided) {
+      const pre = decidePreCapture(policy, {
+        hasExplicitTarget: Boolean(opts.hwnd || opts.processName),
+        requestedProcessName: opts.processName ?? null
+      });
+      if (!pre.allowed) {
+        jsonOut2({
+          sessionId: opts.session ?? null,
+          granted: false,
+          denied: true,
+          denialReason: pre.denialReason,
+          reason: pre.reason,
+          capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          platform: process.platform,
+          permission: { ...permission, granted: false }
+        });
+        return;
+      }
     }
-    const after = opts.after === void 0 ? void 0 : parseNonNegativeIntegerOption("after", opts.after);
-    const limit = parseNonNegativeIntegerOption("limit", opts.limit);
-    const observations = readUiObservationLog(opts.session).filter((report) => after === void 0 || report.sequence > after).slice(0, limit);
-    const last = observations[observations.length - 1];
+    const outputPath = opts.image ?? opts.output ?? join12(tmpdir(), `zam-capture-${randomBytes(4).toString("hex")}.png`);
+    const captureResult = isProvided ? { method: "provided", target: null } : captureScreenshot(outputPath, opts.hwnd, opts.processName);
+    if (!isProvided) {
+      const post = decidePostCapture(policy, {
+        method: captureResult.method,
+        processName: captureResult.target?.processName ?? null,
+        windowTitle: captureResult.target?.windowTitle ?? null
+      });
+      if (!post.allowed) {
+        if (!opts.output) {
+          try {
+            rmSync2(outputPath, { force: true });
+          } catch {
+          }
+        }
+        jsonOut2({
+          sessionId: opts.session ?? null,
+          granted: false,
+          denied: true,
+          denialReason: post.denialReason,
+          reason: post.reason,
+          capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          platform: process.platform,
+          permission: { ...permission, granted: false }
+        });
+        return;
+      }
+    }
+    const imageBytes = readFileSync10(outputPath);
+    const base64 = imageBytes.toString("base64");
     jsonOut2({
-      sessionId: opts.session,
-      executionContext: session.execution_context,
-      observationSource: "ui",
-      logExists: uiObservationLogExists(opts.session),
-      after: after ?? null,
-      count: observations.length,
-      nextSequence: last?.sequence ?? after ?? null,
-      observations
+      sessionId: opts.session ?? null,
+      granted: true,
+      imagePath: outputPath,
+      base64,
+      mimeType: "image/png",
+      captureMethod: captureResult.method,
+      captureTarget: captureResult.target,
+      capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      platform: process.platform,
+      permission: { ...permission, granted: true }
     });
   });
 });
-bridgeCommand.command("get-observations").description("Read UI observer reports for a session (JSON)").requiredOption("--session <id>", "Observer session ID").option("--after <n>", "Only return observations after this sequence").option("--limit <n>", "Maximum observations to return", "100").action((opts) => {
-  try {
-    const after = opts.after === void 0 ? void 0 : parseNonNegativeIntegerOption("after", opts.after);
-    const limit = parseNonNegativeIntegerOption("limit", opts.limit);
-    const observations = readUiObservationLog(opts.session).filter((report) => after === void 0 || report.sequence > after).slice(0, limit);
-    const last = observations[observations.length - 1];
+bridgeCommand.command("get-observer-policy").description(
+  "Report the resolved observer policy so an agent can check before capturing (JSON)"
+).action(async () => {
+  await withDb2(async (db) => {
+    const policy = await resolveObserverPolicy(db);
     jsonOut2({
-      sessionId: opts.session,
-      after: after ?? null,
-      count: observations.length,
-      nextSequence: last?.sequence ?? after ?? null,
-      observations
+      scope: policy.scope,
+      consent: policy.consent,
+      retention: policy.retention,
+      allowlist: policy.allowlist,
+      denylist: policy.denylist,
+      redactWindowTitles: policy.redactWindowTitles,
+      audioOptIn: policy.audioOptIn,
+      builtInSensitiveAlwaysRefused: true,
+      builtInSensitiveMatchers: [...BUILT_IN_SENSITIVE_MATCHERS]
     });
-  } catch (err) {
-    jsonError(err.message);
-  }
+  });
 });
-bridgeCommand.command("observe-ui-snapshot").description(
-  "Analyze a captured UI snapshot with the configured vision LLM (JSON)"
-).requiredOption("--session <id>", "Observer session ID").requiredOption("--sequence <n>", "Monotonic observation sequence number").requiredOption("--image <path>", "PNG snapshot path").requiredOption("--observed-from <iso>", "Observation window start time").requiredOption("--observed-to <iso>", "Observation window end time").requiredOption("--process-name <name>", "Observed application process name").option("--process-id <n>", "Observed application process ID").option("--window-title <title>", "Observed window title").option("--evidence-ref <ref>", "Evidence reference to put in the report").option("--model <model>", "Override configured LLM model for this request").option("--max-tokens <n>", "Model response token budget").option("--timeout <ms>", "Hard request timeout in milliseconds").option("--redacted", "Mark the snapshot evidence as redacted").option("--write-log", "Append the generated report to the session JSONL").action(async (opts) => {
-  const sequence = parseNonNegativeIntegerOption("sequence", opts.sequence);
-  const processId = opts.processId === void 0 ? void 0 : parseNonNegativeIntegerOption("process-id", opts.processId);
-  const maxTokens = opts.maxTokens === void 0 ? void 0 : parseNonNegativeIntegerOption("max-tokens", opts.maxTokens);
-  const hardTimeoutMs = opts.timeout === void 0 ? void 0 : parseNonNegativeIntegerOption("timeout", opts.timeout);
+bridgeCommand.command("sync-observer-policy").description(
+  "Write the resolved observer policy to the native sidecar file (JSON)"
+).action(async () => {
   await withDb2(async (db) => {
-    const report = await observeUiSnapshotViaLLM(db, {
-      sessionId: opts.session,
-      sequence,
-      observedFrom: opts.observedFrom,
-      observedTo: opts.observedTo,
-      imagePath: opts.image,
-      application: {
-        processName: opts.processName,
-        processId,
-        windowTitle: opts.windowTitle
-      },
-      evidenceRef: opts.evidenceRef,
-      redacted: opts.redacted === true,
-      model: opts.model,
-      maxTokens,
-      hardTimeoutMs
-    });
-    if (opts.writeLog === true) {
-      appendUiObservationReport(report);
-    }
-    jsonOut2(report);
+    const { path, policy } = await syncObserverSidecarPolicy(db);
+    jsonOut2({ synced: true, path, policy });
   });
 });
 bridgeCommand.command("check-llm").description("Check if LLM is enabled and online (JSON)").action(async () => {
@@ -6698,26 +7505,26 @@ async function setupTurso(urlArg, tokenArg, mode) {
 
 // src/cli/commands/git-sync.ts
 import { execSync as execSync4 } from "child_process";
-import { chmodSync as chmodSync2, existsSync as existsSync13, writeFileSync as writeFileSync5 } from "fs";
-import { join as join12 } from "path";
+import { chmodSync as chmodSync2, existsSync as existsSync13, writeFileSync as writeFileSync6 } from "fs";
+import { join as join13 } from "path";
 import { Command as Command5 } from "commander";
 function installHook2() {
-  const gitDir = join12(process.cwd(), ".git");
+  const gitDir = join13(process.cwd(), ".git");
   if (!existsSync13(gitDir)) {
     console.error(
       "Error: Current directory is not the root of a Git repository."
     );
     process.exit(1);
   }
-  const hooksDir = join12(gitDir, "hooks");
-  const hookPath = join12(hooksDir, "post-commit");
+  const hooksDir = join13(gitDir, "hooks");
+  const hookPath = join13(hooksDir, "post-commit");
   const hookContent = `#!/bin/sh
 # ZAM Spaced Repetition Auto-Stale Hook
 # Triggered automatically on git commits to decay modified concept cards.
 zam git-sync --commit HEAD --quiet
 `;
   try {
-    writeFileSync5(hookPath, hookContent, { encoding: "utf-8", flag: "w" });
+    writeFileSync6(hookPath, hookContent, { encoding: "utf-8", flag: "w" });
     try {
       chmodSync2(hookPath, "755");
     } catch (_e) {
@@ -6819,7 +7626,7 @@ ZAM Auto-Stale Complete: Scanned ${changedFiles.length} file(s).`
 });
 
 // src/cli/commands/goal.ts
-import { existsSync as existsSync14, mkdirSync as mkdirSync7 } from "fs";
+import { existsSync as existsSync14, mkdirSync as mkdirSync8 } from "fs";
 import { resolve as resolve3 } from "path";
 import { input as input2 } from "@inquirer/prompts";
 import { Command as Command6 } from "commander";
@@ -6945,7 +7752,7 @@ ${"\u2500".repeat(50)}`);
 goalCommand.command("create").description("Create a new goal").option("--slug <slug>", "Goal slug (used as filename)").option("--title <title>", "Goal title").option("--parent <slug>", "Parent goal slug").option("--description <text>", "Goal description").option("--json", "Output as JSON").action(async (opts) => {
   const goalsDir = await resolveGoalsDir();
   if (!existsSync14(goalsDir)) {
-    mkdirSync7(goalsDir, { recursive: true });
+    mkdirSync8(goalsDir, { recursive: true });
   }
   let slug = opts.slug;
   let title = opts.title;
@@ -7004,9 +7811,9 @@ goalCommand.command("status <slug> <status>").description("Update a goal's statu
 });
 
 // src/cli/commands/init.ts
-import { existsSync as existsSync15, mkdirSync as mkdirSync8, writeFileSync as writeFileSync6 } from "fs";
+import { existsSync as existsSync15, mkdirSync as mkdirSync9, writeFileSync as writeFileSync7 } from "fs";
 import { homedir as homedir9 } from "os";
-import { join as join13 } from "path";
+import { join as join14 } from "path";
 import { confirm, input as input3 } from "@inquirer/prompts";
 import { Command as Command7 } from "commander";
 var HOME2 = homedir9();
@@ -7014,12 +7821,12 @@ function printLine(char = "\u2550", len = 60, color = "\x1B[36m") {
   console.log(`${color}${char.repeat(len)}\x1B[0m`);
 }
 function bootstrapSandboxWorkspace(workspaceDir) {
-  mkdirSync8(join13(workspaceDir, "beliefs"), { recursive: true });
-  mkdirSync8(join13(workspaceDir, "goals"), { recursive: true });
-  mkdirSync8(join13(workspaceDir, "skills"), { recursive: true });
-  const worldviewFile = join13(workspaceDir, "beliefs", "worldview.md");
+  mkdirSync9(join14(workspaceDir, "beliefs"), { recursive: true });
+  mkdirSync9(join14(workspaceDir, "goals"), { recursive: true });
+  mkdirSync9(join14(workspaceDir, "skills"), { recursive: true });
+  const worldviewFile = join14(workspaceDir, "beliefs", "worldview.md");
   if (!existsSync15(worldviewFile)) {
-    writeFileSync6(
+    writeFileSync7(
       worldviewFile,
       `# Personal Worldview
 
@@ -7031,9 +7838,9 @@ Here, I declare the core concepts and principles I want to master.
       "utf8"
     );
   }
-  const goalsFile = join13(workspaceDir, "goals", "goals.md");
+  const goalsFile = join14(workspaceDir, "goals", "goals.md");
   if (!existsSync15(goalsFile)) {
-    writeFileSync6(
+    writeFileSync7(
       goalsFile,
       `# Personal Goals
 
@@ -7055,7 +7862,7 @@ var initCommand = new Command7("init").description("Launch the guided interactiv
   );
   printLine();
   console.log("\n\x1B[1m[1/5] Setting up Local Workspace Sandbox\x1B[0m");
-  const defaultWorkspace = join13(HOME2, "Documents", "zam");
+  const defaultWorkspace = join14(HOME2, "Documents", "zam");
   const workspacePath = await input3({
     message: "Choose your ZAM workspace directory:",
     default: defaultWorkspace
@@ -7752,10 +8559,10 @@ ${"\u2550".repeat(50)}`);
 });
 
 // src/cli/commands/monitor.ts
-import { execFileSync as execFileSync2, execSync as execSync5 } from "child_process";
-import { unlinkSync, writeFileSync as writeFileSync7 } from "fs";
-import { tmpdir } from "os";
-import { basename as basename3, join as join14 } from "path";
+import { execFileSync as execFileSync3, execSync as execSync5 } from "child_process";
+import { unlinkSync, writeFileSync as writeFileSync8 } from "fs";
+import { tmpdir as tmpdir2 } from "os";
+import { basename as basename3, join as join15 } from "path";
 import { Command as Command9 } from "commander";
 function isPowerShellShell(shell) {
   return shell === "pwsh" || shell === "powershell";
@@ -7906,11 +8713,23 @@ monitorCommand.command("status").description("Show monitoring status for a sessi
     console.log(`  To:       ${result.timeSpan.end}`);
   }
 });
+function selectWindowsExecutable(results, pathext = process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD") {
+  if (results.length === 0) return null;
+  const extensions = pathext.split(";").map((ext) => ext.trim().toLowerCase()).filter(Boolean);
+  const runnable = results.find(
+    (result) => extensions.some((ext) => result.toLowerCase().endsWith(ext))
+  );
+  return runnable ?? results[0];
+}
 function findExecutable(command) {
   try {
     const lookup = process.platform === "win32" ? `where.exe ${command}` : `command -v ${command}`;
-    const result = execSync5(lookup, { encoding: "utf-8" }).split(/\r?\n/)[0]?.trim();
-    return result || null;
+    const results = execSync5(lookup, { encoding: "utf-8" }).split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    if (results.length === 0) return null;
+    if (process.platform === "win32") {
+      return selectWindowsExecutable(results);
+    }
+    return results[0];
   } catch {
     return null;
   }
@@ -7920,8 +8739,8 @@ function resolveZamInvocation(shell) {
   if (installed) {
     return isPowerShellShell(shell) ? `& ${psSingleQuoted2(installed)}` : installed;
   }
-  const projectRoot = join14(import.meta.dirname, "..", "..", "..");
-  const cliSource = join14(projectRoot, "src/cli/index.ts");
+  const projectRoot = join15(import.meta.dirname, "..", "..", "..");
+  const cliSource = join15(projectRoot, "src/cli/index.ts");
   if (isPowerShellShell(shell)) {
     return `& npx --prefix ${psSingleQuoted2(projectRoot)} tsx ${psSingleQuoted2(cliSource)}`;
   }
@@ -8011,9 +8830,9 @@ end tell` : `tell application "Terminal"
   activate
   do script "${escaped}"
 end tell`;
-  const tmpFile = join14(tmpdir(), `zam-monitor-${sessionId}.scpt`);
+  const tmpFile = join15(tmpdir2(), `zam-monitor-${sessionId}.scpt`);
   try {
-    writeFileSync7(tmpFile, appleScript);
+    writeFileSync8(tmpFile, appleScript);
     execSync5(`osascript ${JSON.stringify(tmpFile)}`, { stdio: "ignore" });
     console.log(
       `Opened ${useIterm ? "iTerm2" : "Terminal.app"} window with monitoring for session ${sessionId}`
@@ -8040,9 +8859,10 @@ function openWindowsPowerShell(shellSetup, sessionId, dir, requestedShell) {
     `-FilePath ${psSingleQuoted2(executable)}`,
     `-ArgumentList @('-NoExit','-NoProfile','-Command',${psSingleQuoted2(shellSetup)})`
   ].join(" ");
+  const launcher = findExecutable("pwsh.exe") ? "pwsh.exe" : "powershell.exe";
   try {
-    execFileSync2(
-      "powershell.exe",
+    execFileSync3(
+      launcher,
       ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", startCommand],
       {
         stdio: "ignore"
@@ -8061,10 +8881,73 @@ Run this manually in a new PowerShell terminal:
   }
 }
 
+// src/cli/commands/observer.ts
+import { Command as Command10 } from "commander";
+var observerCommand = new Command10("observer").description(
+  "Configure what the UI observer may capture (Layer 2 policy)"
+);
+function applyObserverListChange(current, entry, op) {
+  const normalized = entry.trim().toLowerCase();
+  const list = parseObserverList(current);
+  const next = op === "add" ? [.../* @__PURE__ */ new Set([...list, normalized])] : list.filter((item) => item !== normalized);
+  return next.join(",");
+}
+observerCommand.command("status").description("Show the active observer policy").option("--json", "Output as JSON").action(async (opts) => {
+  await withDb(async (db) => {
+    const policy = await resolveObserverPolicy(db);
+    if (opts.json) {
+      console.log(JSON.stringify(policy, null, 2));
+      return;
+    }
+    console.log("Observer policy:\n");
+    console.log(`  Scope:         ${policy.scope}`);
+    console.log(`  Consent:       ${policy.consent}`);
+    console.log(`  Retention:     ${policy.retention}`);
+    console.log(
+      `  Allowlist:     ${policy.allowlist.length ? policy.allowlist.join(", ") : "(any targeted window)"}`
+    );
+    console.log(
+      `  Denylist:      ${policy.denylist.length ? policy.denylist.join(", ") : "(none)"}`
+    );
+    console.log(`  Redact titles: ${policy.redactWindowTitles}`);
+    console.log(
+      "\nBuilt-in sensitive surfaces (password managers, auth/UAC dialogs, banking) are always refused and cannot be allowlisted."
+    );
+  });
+});
+observerCommand.command("grant <process>").description(
+  "Allow the observer to capture a process (adds it to observer.allowlist)"
+).action(async (processName) => {
+  await withDb(async (db) => {
+    const next = applyObserverListChange(
+      await getSetting(db, "observer.allowlist"),
+      processName,
+      "add"
+    );
+    await setSetting(db, "observer.allowlist", next);
+    await syncObserverSidecarPolicy(db);
+    console.log(`Granted: ${processName.trim().toLowerCase()}`);
+    console.log(`observer.allowlist = ${next || "(empty)"}`);
+  });
+});
+observerCommand.command("revoke <process>").description("Remove a process from observer.allowlist").action(async (processName) => {
+  await withDb(async (db) => {
+    const next = applyObserverListChange(
+      await getSetting(db, "observer.allowlist"),
+      processName,
+      "remove"
+    );
+    await setSetting(db, "observer.allowlist", next);
+    await syncObserverSidecarPolicy(db);
+    console.log(`Revoked: ${processName.trim().toLowerCase()}`);
+    console.log(`observer.allowlist = ${next || "(empty)"}`);
+  });
+});
+
 // src/cli/commands/profile.ts
 import { homedir as homedir10 } from "os";
-import { dirname as dirname5, join as join15, resolve as resolve4 } from "path";
-import { Command as Command10 } from "commander";
+import { dirname as dirname5, join as join16, resolve as resolve4 } from "path";
+import { Command as Command11 } from "commander";
 var C2 = {
   reset: "\x1B[0m",
   bold: "\x1B[1m",
@@ -8073,7 +8956,7 @@ var C2 = {
   green: "\x1B[32m"
 };
 function defaultPersonalDir() {
-  return join15(homedir10(), "Documents", "zam");
+  return join16(homedir10(), "Documents", "zam");
 }
 function render(profile) {
   const sync = profile.syncProvider ? `${C2.green}${profile.syncProvider}${C2.reset} ${C2.dim}(good for cross-device snapshots)${C2.reset}` : `${C2.dim}local folder (use a synced folder or snapshots to move between machines)${C2.reset}`;
@@ -8084,7 +8967,7 @@ function render(profile) {
   console.log(`  data dir:      ${C2.cyan}${profile.dataDir}${C2.reset}`);
   console.log(`  database:      ${C2.cyan}${profile.dbPath}${C2.reset}`);
 }
-var profileCommand = new Command10("profile").description("Show or change this machine's ZAM install profile").option("--mode <mode>", "Set install mode: developer | default").option("--dir <path>", "Set the personal-content folder").option("--json", "Output as JSON").action(async (opts) => {
+var profileCommand = new Command11("profile").description("Show or change this machine's ZAM install profile").option("--mode <mode>", "Set install mode: developer | default").option("--dir <path>", "Set the personal-content folder").option("--json", "Output as JSON").action(async (opts) => {
   if (opts.mode && opts.mode !== "developer" && opts.mode !== "default") {
     console.error(`Invalid --mode: ${opts.mode}. Use developer or default.`);
     process.exit(1);
@@ -8120,8 +9003,8 @@ var profileCommand = new Command10("profile").description("Show or change this m
 });
 
 // src/cli/commands/review.ts
-import { Command as Command11 } from "commander";
-var reviewCommand = new Command11("review").description("Start an interactive review session").option("--user <id>", "User ID (default: whoami)").option("--max-new <n>", "Maximum new cards", "10").option("--max-reviews <n>", "Maximum review cards", "50").option("--no-resolve", "Skip resolving source_link into inline context").action(async (opts) => {
+import { Command as Command12 } from "commander";
+var reviewCommand = new Command12("review").description("Start an interactive review session").option("--user <id>", "User ID (default: whoami)").option("--max-new <n>", "Maximum new cards", "10").option("--max-reviews <n>", "Maximum review cards", "50").option("--no-resolve", "Skip resolving source_link into inline context").action(async (opts) => {
   let db;
   try {
     db = await openDatabase();
@@ -8234,10 +9117,10 @@ ${"\u2550".repeat(50)}`);
 });
 
 // src/cli/commands/session.ts
-import { readFileSync as readFileSync10 } from "fs";
+import { readFileSync as readFileSync11 } from "fs";
 import { input as input6, select as select2 } from "@inquirer/prompts";
-import { Command as Command12 } from "commander";
-var sessionCommand = new Command12("session").description(
+import { Command as Command13 } from "commander";
+var sessionCommand = new Command13("session").description(
   "Manage learning sessions"
 );
 sessionCommand.command("start").description("Start a new learning session (review \u2192 task)").option("--user <id>", "User ID (default: whoami)").option("--task <description>", "Task description (interactive if omitted)").option(
@@ -8289,11 +9172,18 @@ sessionCommand.command("start").description("Start a new learning session (revie
       task,
       execution_context: opts.context
     });
+    const observerHint = opts.context === "ui" && !await isObserverPolicyConfigured(db) ? OBSERVER_POLICY_UNSET_HINT : null;
     await db.close();
     if (opts.quiet) {
       console.log(session.id);
     } else if (opts.json) {
-      console.log(JSON.stringify(session, null, 2));
+      console.log(
+        JSON.stringify(
+          observerHint ? { ...session, observerPolicyHint: observerHint } : session,
+          null,
+          2
+        )
+      );
     } else {
       console.log(`
 Session started: ${session.id}`);
@@ -8301,6 +9191,10 @@ Session started: ${session.id}`);
       console.log(`  Task:    ${session.task}`);
       console.log(`  Context: ${session.execution_context}`);
       console.log(`  Started: ${session.started_at}`);
+      if (observerHint) {
+        console.log(`
+${observerHint}`);
+      }
     }
   } catch (err) {
     await db?.close();
@@ -8415,7 +9309,7 @@ function loadPatternFile(path) {
   if (!path) return [];
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync10(path, "utf-8"));
+    parsed = JSON.parse(readFileSync11(path, "utf-8"));
   } catch (err) {
     throw new Error(
       `Cannot read synthesis patterns from ${path}: ${err.message}`
@@ -8606,8 +9500,8 @@ sessionCommand.command("end").description("End a session and show summary").requ
 
 // src/cli/commands/settings.ts
 import { existsSync as existsSync16 } from "fs";
-import { Command as Command13 } from "commander";
-var settingsCommand = new Command13("settings").description(
+import { Command as Command14 } from "commander";
+var settingsCommand = new Command14("settings").description(
   "Manage user settings"
 );
 var BOOLEAN_SETTING_KEYS = /* @__PURE__ */ new Set(["llm.enabled", "llm.vision.enabled"]);
@@ -8661,6 +9555,9 @@ settingsCommand.command("set <key> <value>").description("Set a setting").option
   await withDb(async (db) => {
     const parsedVal = normalizeSettingValue(key, value);
     await setSetting(db, key, parsedVal);
+    if (key.startsWith("observer.")) {
+      await syncObserverSidecarPolicy(db);
+    }
     if (!opts.quiet) {
       console.log(`Set ${key} = ${parsedVal}`);
     }
@@ -8669,6 +9566,9 @@ settingsCommand.command("set <key> <value>").description("Set a setting").option
 settingsCommand.command("delete <key>").description("Delete a setting").option("--quiet", "Suppress output").action(async (key, opts) => {
   await withDb(async (db) => {
     const deleted = await deleteSetting(db, key);
+    if (key.startsWith("observer.")) {
+      await syncObserverSidecarPolicy(db);
+    }
     if (!opts.quiet) {
       if (deleted) {
         console.log(`Deleted: ${key}`);
@@ -8776,32 +9676,32 @@ settingsCommand.command("repos").description("Show or set Personal, Team, and Or
 });
 
 // src/cli/commands/setup.ts
-import { copyFileSync as copyFileSync2, existsSync as existsSync17, mkdirSync as mkdirSync9, writeFileSync as writeFileSync8 } from "fs";
-import { basename as basename4, dirname as dirname6, join as join16 } from "path";
+import { copyFileSync as copyFileSync2, existsSync as existsSync17, mkdirSync as mkdirSync10, writeFileSync as writeFileSync9 } from "fs";
+import { basename as basename4, dirname as dirname6, join as join17 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import { Command as Command14 } from "commander";
+import { Command as Command15 } from "commander";
 var packageRoot = [
   fileURLToPath2(new URL("../..", import.meta.url)),
   fileURLToPath2(new URL("../../..", import.meta.url))
-].find((candidate) => existsSync17(join16(candidate, "package.json"))) ?? fileURLToPath2(new URL("../..", import.meta.url));
+].find((candidate) => existsSync17(join17(candidate, "package.json"))) ?? fileURLToPath2(new URL("../..", import.meta.url));
 var SKILL_PAIRS = [
   {
-    from: join16(packageRoot, ".claude", "skills", "zam", "SKILL.md"),
-    to: join16(".claude", "skills", "zam", "SKILL.md")
+    from: join17(packageRoot, ".claude", "skills", "zam", "SKILL.md"),
+    to: join17(".claude", "skills", "zam", "SKILL.md")
   },
   {
-    from: join16(packageRoot, ".agent", "skills", "zam", "SKILL.md"),
-    to: join16(".agent", "skills", "zam", "SKILL.md")
+    from: join17(packageRoot, ".agent", "skills", "zam", "SKILL.md"),
+    to: join17(".agent", "skills", "zam", "SKILL.md")
   },
   {
-    from: join16(packageRoot, ".agents", "skills", "zam", "SKILL.md"),
-    to: join16(".agents", "skills", "zam", "SKILL.md")
+    from: join17(packageRoot, ".agents", "skills", "zam", "SKILL.md"),
+    to: join17(".agents", "skills", "zam", "SKILL.md")
   }
 ];
 function copySkills(force, cwd = process.cwd()) {
   let anyAction = false;
   for (const { from, to } of SKILL_PAIRS) {
-    const dest = join16(cwd, to);
+    const dest = join17(cwd, to);
     if (!existsSync17(from)) {
       console.warn(`  warn  source not found, skipping: ${from}`);
       continue;
@@ -8810,7 +9710,7 @@ function copySkills(force, cwd = process.cwd()) {
       console.log(`  skip  ${to} (already present \xE2\u20AC\u201D use --force to update)`);
       continue;
     }
-    mkdirSync9(dirname6(dest), { recursive: true });
+    mkdirSync10(dirname6(dest), { recursive: true });
     copyFileSync2(from, dest);
     console.log(`  copy  ${to}`);
     anyAction = true;
@@ -8821,13 +9721,25 @@ function copySkills(force, cwd = process.cwd()) {
     );
   }
 }
+function formatDatabaseInitTarget(target) {
+  switch (target.kind) {
+    case "local":
+      return `ZAM database at ${target.location} (local SQLite)`;
+    case "turso-remote":
+      return `ZAM database via Turso remote at ${target.location}`;
+    case "turso-native":
+      return `ZAM database via Turso native driver at ${target.location}`;
+    case "turso-replica":
+      return `ZAM database replica at ${target.location} syncing from ${target.syncUrl}`;
+  }
+}
 async function initDatabase(skipInit) {
   if (skipInit) return;
   try {
-    const dbPath = getDefaultDbPath();
+    const target = getDatabaseTargetInfo();
     const db = await openDatabaseWithSync({ initialize: true });
     await db.close();
-    console.log(`  init  ZAM database at ${dbPath}`);
+    console.log(`  init  ${formatDatabaseInitTarget(target)}`);
   } catch (err) {
     const msg = err.message;
     if (!msg.includes("already")) {
@@ -8839,13 +9751,13 @@ async function initDatabase(skipInit) {
 }
 function writeClaudeMd(skipClaudeMd, cwd = process.cwd()) {
   if (skipClaudeMd) return;
-  const dest = join16(cwd, "CLAUDE.md");
+  const dest = join17(cwd, "CLAUDE.md");
   if (existsSync17(dest)) {
     console.log(`  skip  CLAUDE.md (already present)`);
     return;
   }
   const name = basename4(cwd);
-  writeFileSync8(
+  writeFileSync9(
     dest,
     `# ZAM Personal Kernel \xE2\u20AC\u201D ${name}
 
@@ -8873,13 +9785,13 @@ Use \`zam connector setup turso\` to store cloud credentials in
 }
 function writeAgentsMd(skipAgentsMd, cwd = process.cwd()) {
   if (skipAgentsMd) return;
-  const dest = join16(cwd, "AGENTS.md");
+  const dest = join17(cwd, "AGENTS.md");
   if (existsSync17(dest)) {
     console.log(`  skip  AGENTS.md (already present)`);
     return;
   }
   const name = basename4(cwd);
-  writeFileSync8(
+  writeFileSync9(
     dest,
     `# ZAM Personal Kernel - ${name}
 
@@ -8912,7 +9824,7 @@ Codex discovers repository skills under \`.agents/skills/\`. Run
   );
   console.log(`  write AGENTS.md`);
 }
-var setupCommand = new Command14("setup").description(
+var setupCommand = new Command15("setup").description(
   "Distribute ZAM skill files into this personal instance and initialize the database"
 ).option(
   "--force",
@@ -8933,8 +9845,8 @@ var setupCommand = new Command14("setup").description(
 );
 
 // src/cli/commands/skill.ts
-import { Command as Command15 } from "commander";
-var skillCommand = new Command15("skill").description(
+import { Command as Command16 } from "commander";
+var skillCommand = new Command16("skill").description(
   "Manage agent skill entries (task recipes)"
 );
 skillCommand.command("list").description("List all agent skills").option("--json", "Output as JSON").action(async (opts) => {
@@ -9019,10 +9931,10 @@ skillCommand.command("add").description("Register a new agent skill").requiredOp
 });
 
 // src/cli/commands/snapshot.ts
-import { existsSync as existsSync18, mkdirSync as mkdirSync10, readFileSync as readFileSync11, writeFileSync as writeFileSync9 } from "fs";
+import { existsSync as existsSync18, mkdirSync as mkdirSync11, readFileSync as readFileSync12, writeFileSync as writeFileSync10 } from "fs";
 import { homedir as homedir11 } from "os";
-import { dirname as dirname7, join as join17 } from "path";
-import { Command as Command16 } from "commander";
+import { dirname as dirname7, join as join18 } from "path";
+import { Command as Command17 } from "commander";
 function defaultOutName() {
   const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d+Z$/, "").replace(/:/g, "-");
   return `zam-snapshot-${stamp}.sql`;
@@ -9036,12 +9948,12 @@ function summarize(tables) {
   }
   return { total, nonEmpty };
 }
-var exportCmd = new Command16("export").description("Write a portable SQL-text snapshot of the database").option("--out <file>", "Output file (use - for stdout)").action(async (opts) => {
+var exportCmd = new Command17("export").description("Write a portable SQL-text snapshot of the database").option("--out <file>", "Output file (use - for stdout)").action(async (opts) => {
   let db;
   try {
     db = await openDatabaseWithSync({ initialize: true });
     const snapshot = await exportSnapshot(db);
-    const personalDir = await getSetting(db, "personal.workspace_dir") || join17(homedir11(), "Documents", "zam");
+    const personalDir = await getSetting(db, "personal.workspace_dir") || join18(homedir11(), "Documents", "zam");
     await db.close();
     db = void 0;
     const manifest = verifySnapshot(snapshot);
@@ -9050,12 +9962,12 @@ var exportCmd = new Command16("export").description("Write a portable SQL-text s
       process.stdout.write(snapshot);
       return;
     }
-    const out = opts.out ?? join17(personalDir, "snapshots", defaultOutName());
+    const out = opts.out ?? join18(personalDir, "snapshots", defaultOutName());
     const dir = dirname7(out);
     if (dir && dir !== "." && !existsSync18(dir)) {
-      mkdirSync10(dir, { recursive: true });
+      mkdirSync11(dir, { recursive: true });
     }
-    writeFileSync9(out, snapshot, "utf-8");
+    writeFileSync10(out, snapshot, "utf-8");
     console.log(`Snapshot written: ${out}`);
     console.log(
       `  ${total} row(s)${nonEmpty.length ? ` \u2014 ${nonEmpty.join(", ")}` : ""}`
@@ -9066,14 +9978,14 @@ var exportCmd = new Command16("export").description("Write a portable SQL-text s
     process.exit(1);
   }
 });
-var importCmd = new Command16("import").description("Restore a snapshot into the database").argument("<file>", "Snapshot file to restore").option("--force", "Overwrite a non-empty database", false).action(async (file, opts) => {
+var importCmd = new Command17("import").description("Restore a snapshot into the database").argument("<file>", "Snapshot file to restore").option("--force", "Overwrite a non-empty database", false).action(async (file, opts) => {
   let db;
   try {
     if (!existsSync18(file)) {
       console.error(`Error: Snapshot file not found: ${file}`);
       process.exit(1);
     }
-    const snapshot = readFileSync11(file, "utf-8");
+    const snapshot = readFileSync12(file, "utf-8");
     db = await openDatabaseWithSync({ initialize: true });
     const result = await importSnapshot(db, snapshot, { force: opts.force });
     await db.close();
@@ -9089,13 +10001,13 @@ var importCmd = new Command16("import").description("Restore a snapshot into the
     process.exit(1);
   }
 });
-var verifyCmd = new Command16("verify").description("Check a snapshot's manifest and checksum without importing").argument("<file>", "Snapshot file to verify").action((file) => {
+var verifyCmd = new Command17("verify").description("Check a snapshot's manifest and checksum without importing").argument("<file>", "Snapshot file to verify").action((file) => {
   try {
     if (!existsSync18(file)) {
       console.error(`Error: Snapshot file not found: ${file}`);
       process.exit(1);
     }
-    const manifest = verifySnapshot(readFileSync11(file, "utf-8"));
+    const manifest = verifySnapshot(readFileSync12(file, "utf-8"));
     const { total, nonEmpty } = summarize(manifest.tables);
     console.log(`Valid snapshot (format v${manifest.version})`);
     console.log(`  created: ${manifest.createdAt}`);
@@ -9107,11 +10019,11 @@ var verifyCmd = new Command16("verify").description("Check a snapshot's manifest
     process.exit(1);
   }
 });
-var snapshotCommand = new Command16("snapshot").description("Export, import, or verify a portable database snapshot").addCommand(exportCmd).addCommand(importCmd).addCommand(verifyCmd);
+var snapshotCommand = new Command17("snapshot").description("Export, import, or verify a portable database snapshot").addCommand(exportCmd).addCommand(importCmd).addCommand(verifyCmd);
 
 // src/cli/commands/stats.ts
-import { Command as Command17 } from "commander";
-var statsCommand = new Command17("stats").description("Show learning dashboard for a user").option("--user <id>", "User ID (default: whoami)").option("--json", "Output as JSON").action(async (opts) => {
+import { Command as Command18 } from "commander";
+var statsCommand = new Command18("stats").description("Show learning dashboard for a user").option("--user <id>", "User ID (default: whoami)").option("--json", "Output as JSON").action(async (opts) => {
   await withDb(async (db) => {
     const userId = await resolveUser(opts, db);
     const stats = await getUserStats(db, userId);
@@ -9147,8 +10059,8 @@ var statsCommand = new Command17("stats").description("Show learning dashboard f
 });
 
 // src/cli/commands/token.ts
-import { Command as Command18 } from "commander";
-var tokenCommand = new Command18("token").description(
+import { Command as Command19 } from "commander";
+var tokenCommand = new Command19("token").description(
   "Manage knowledge tokens"
 );
 tokenCommand.command("register").description("Register a new knowledge token").requiredOption("--slug <slug>", "Unique token slug").requiredOption("--concept <concept>", "Concept description").option("--domain <domain>", "Knowledge domain", "").option("--bloom <level>", "Bloom taxonomy level (1-5)", "1").option("--source-link <link>", "Source file path or reference URL", "").option("--question <question>", "Specific question prompt for recall", "").option("--json", "Output as JSON").option("--quiet", "Suppress output (exit code only)").action(async (opts) => {
@@ -9437,9 +10349,9 @@ tokenCommand.command("status").description("Show full status of a token for a us
 import { spawn as spawn2, spawnSync } from "child_process";
 import { existsSync as existsSync19 } from "fs";
 import { homedir as homedir12 } from "os";
-import { dirname as dirname8, join as join18 } from "path";
+import { dirname as dirname8, join as join19 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
-import { Command as Command19 } from "commander";
+import { Command as Command20 } from "commander";
 var C3 = {
   reset: "\x1B[0m",
   red: "\x1B[31m",
@@ -9453,8 +10365,8 @@ function findDesktopDir() {
   for (const start of starts) {
     let dir = start;
     for (let i = 0; i < 10; i++) {
-      if (existsSync19(join18(dir, "desktop", "src-tauri", "tauri.conf.json"))) {
-        return join18(dir, "desktop");
+      if (existsSync19(join19(dir, "desktop", "src-tauri", "tauri.conf.json"))) {
+        return join19(dir, "desktop");
       }
       const parent = dirname8(dir);
       if (parent === dir) break;
@@ -9464,18 +10376,18 @@ function findDesktopDir() {
   return null;
 }
 function findBuiltApp(desktopDir) {
-  const releaseDir = join18(desktopDir, "src-tauri", "target", "release");
+  const releaseDir = join19(desktopDir, "src-tauri", "target", "release");
   if (process.platform === "win32") {
     for (const name of ["ZAM.exe", "zam.exe", "zam-desktop.exe"]) {
-      const p = join18(releaseDir, name);
+      const p = join19(releaseDir, name);
       if (existsSync19(p)) return p;
     }
   } else if (process.platform === "darwin") {
-    const app = join18(releaseDir, "bundle", "macos", "ZAM.app");
+    const app = join19(releaseDir, "bundle", "macos", "ZAM.app");
     if (existsSync19(app)) return app;
   } else {
     for (const name of ["zam", "ZAM", "zam-desktop"]) {
-      const p = join18(releaseDir, name);
+      const p = join19(releaseDir, name);
       if (existsSync19(p)) return p;
     }
   }
@@ -9483,10 +10395,10 @@ function findBuiltApp(desktopDir) {
 }
 function findInstalledApp() {
   const candidates = process.platform === "win32" ? [
-    process.env.LOCALAPPDATA && join18(process.env.LOCALAPPDATA, "Programs", "ZAM", "ZAM.exe"),
-    process.env.ProgramFiles && join18(process.env.ProgramFiles, "ZAM", "ZAM.exe"),
-    process.env["ProgramFiles(x86)"] && join18(process.env["ProgramFiles(x86)"], "ZAM", "ZAM.exe")
-  ] : process.platform === "darwin" ? ["/Applications/ZAM.app", join18(homedir12(), "Applications", "ZAM.app")] : ["/opt/ZAM/zam", "/usr/bin/zam-desktop"];
+    process.env.LOCALAPPDATA && join19(process.env.LOCALAPPDATA, "Programs", "ZAM", "ZAM.exe"),
+    process.env.ProgramFiles && join19(process.env.ProgramFiles, "ZAM", "ZAM.exe"),
+    process.env["ProgramFiles(x86)"] && join19(process.env["ProgramFiles(x86)"], "ZAM", "ZAM.exe")
+  ] : process.platform === "darwin" ? ["/Applications/ZAM.app", join19(homedir12(), "Applications", "ZAM.app")] : ["/opt/ZAM/zam", "/usr/bin/zam-desktop"];
   return candidates.find((candidate) => candidate && existsSync19(candidate)) || null;
 }
 function runNpm(args, opts) {
@@ -9498,7 +10410,7 @@ function runNpm(args, opts) {
   return res.status ?? 1;
 }
 function ensureDesktopDeps(desktopDir) {
-  if (existsSync19(join18(desktopDir, "node_modules"))) return true;
+  if (existsSync19(join19(desktopDir, "node_modules"))) return true;
   console.log(
     `${C3.cyan}Installing desktop dependencies (one-time)...${C3.reset}`
   );
@@ -9524,7 +10436,7 @@ function requireRust() {
 function hasMsvcBuildTools() {
   if (process.platform !== "win32") return true;
   const pf86 = process.env["ProgramFiles(x86)"] || "C:\\Program Files (x86)";
-  const vswhere = join18(
+  const vswhere = join19(
     pf86,
     "Microsoft Visual Studio",
     "Installer",
@@ -9562,7 +10474,7 @@ function requireMsvcOnWindows() {
   return false;
 }
 function warnIfCliMissing(repoRoot) {
-  if (!existsSync19(join18(repoRoot, "dist", "cli", "index.js"))) {
+  if (!existsSync19(join19(repoRoot, "dist", "cli", "index.js"))) {
     console.warn(
       `${C3.yellow}\u26A0 CLI build not found (dist/cli/index.js). The GUI bridge needs it \u2014 run 'npm run build' at the repo root.${C3.reset}`
     );
@@ -9619,7 +10531,7 @@ function createShortcuts(appPath, repoRoot) {
     console.error(`${C3.red}\u2717 Could not create shortcuts.${C3.reset}`);
   }
 }
-var uiCommand = new Command19("ui").description("Launch the ZAM Desktop GUI (Active-Recall Studio)").option("--dev", "Run in hot-reload development mode (needs Rust)").option(
+var uiCommand = new Command20("ui").description("Launch the ZAM Desktop GUI (Active-Recall Studio)").option("--dev", "Run in hot-reload development mode (needs Rust)").option(
   "--build",
   "Build the native installer for your OS (needs Rust, one-time)"
 ).option("--shortcut", "Create Desktop + Start-menu shortcuts to the GUI").action((opts) => {
@@ -9646,7 +10558,7 @@ var uiCommand = new Command19("ui").description("Launch the ZAM Desktop GUI (Act
     );
     const code = runNpm(["run", "tauri", "build"], { cwd: desktopDir });
     if (code === 0) {
-      const bundle = join18(
+      const bundle = join19(
         desktopDir,
         "src-tauri",
         "target",
@@ -9722,10 +10634,12 @@ ${C3.dim}After that, 'zam ui' launches it directly.${C3.reset}`
 });
 
 // src/cli/commands/update.ts
-import { readFileSync as readFileSync12 } from "fs";
-import { dirname as dirname9, join as join19 } from "path";
+import { spawnSync as spawnSync2 } from "child_process";
+import { existsSync as existsSync20, readFileSync as readFileSync13, realpathSync } from "fs";
+import { dirname as dirname9, join as join20 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
-import { Command as Command20 } from "commander";
+import { confirm as confirm3 } from "@inquirer/prompts";
+import { Command as Command21 } from "commander";
 var GITHUB_REPO = "zam-os/zam";
 var CHANNELS = [
   "developer",
@@ -9739,6 +10653,7 @@ var C4 = {
   cyan: "\x1B[36m",
   dim: "\x1B[2m",
   green: "\x1B[32m",
+  red: "\x1B[31m",
   yellow: "\x1B[33m"
 };
 function currentVersion() {
@@ -9746,7 +10661,7 @@ function currentVersion() {
   for (const up of ["..", "../..", "../../.."]) {
     try {
       const pkg2 = JSON.parse(
-        readFileSync12(join19(here, up, "package.json"), "utf-8")
+        readFileSync13(join20(here, up, "package.json"), "utf-8")
       );
       if (pkg2.version) return pkg2.version;
     } catch {
@@ -9754,6 +10669,16 @@ function currentVersion() {
   }
   return "0.0.0";
 }
+function versionAt(dir) {
+  try {
+    const pkg2 = JSON.parse(
+      readFileSync13(join20(dir, "package.json"), "utf-8")
+    );
+    return pkg2.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
 async function fetchLatestVersion(repo) {
   const res = await fetch(
     `https://api.github.com/repos/${repo}/releases/latest`,
@@ -9792,7 +10717,7 @@ function render2(decision) {
     );
   }
 }
-var checkCmd = new Command20("check").description("Check whether a newer ZAM has been released").option(
+var checkCmd = new Command21("check").description("Check whether a newer ZAM has been released").option(
   "--latest <version>",
   "Compare against this version instead of fetching"
 ).option("--channel <channel>", "Override the detected install channel").option("--json", "Output as JSON").action(
@@ -9823,11 +10748,154 @@ var checkCmd = new Command20("check").description("Check whether a newer ZAM has
     }
   }
 );
-var updateCommand = new Command20("update").description("Check for ZAM updates").addCommand(checkCmd);
+function findSourceRepo() {
+  let dir = realpathSync(dirname9(fileURLToPath4(import.meta.url)));
+  let parent = dirname9(dir);
+  while (parent !== dir) {
+    if (existsSync20(join20(dir, ".git"))) return dir;
+    dir = parent;
+    parent = dirname9(dir);
+  }
+  return existsSync20(join20(dir, ".git")) ? dir : null;
+}
+function runGit(cwd, args, capture) {
+  const res = spawnSync2("git", args, {
+    cwd,
+    stdio: capture ? ["ignore", "pipe", "pipe"] : "inherit",
+    encoding: "utf8"
+  });
+  return { ok: res.status === 0, out: (res.stdout ?? "").trim() };
+}
+function runNpm2(args, cwd) {
+  const res = spawnSync2("npm", args, {
+    cwd,
+    stdio: "inherit",
+    shell: process.platform === "win32"
+  });
+  return res.status ?? 1;
+}
+function runShell(command) {
+  const res = spawnSync2(command, { stdio: "inherit", shell: true });
+  return res.status === 0;
+}
+function applyDeveloperUpdate(force) {
+  if (!hasCommand("git")) {
+    console.error(`${C4.red}\u2717${C4.reset} git was not found on PATH.`);
+    process.exit(1);
+  }
+  const src = findSourceRepo();
+  if (!src) {
+    console.error(
+      `${C4.red}\u2717${C4.reset} Could not locate the ZAM source checkout to update.`
+    );
+    process.exit(1);
+  }
+  const status = runGit(src, ["status", "--porcelain"], true);
+  if (status.ok && status.out && !force) {
+    console.error(
+      `${C4.red}\u2717${C4.reset} The source checkout has uncommitted changes:
+${status.out}
+Commit or stash them, or re-run with ${C4.cyan}--force${C4.reset}.`
+    );
+    process.exit(1);
+  }
+  console.log(
+    `${C4.dim}\u2192 git pull --ff-only${C4.reset}  ${C4.dim}(${src})${C4.reset}`
+  );
+  if (!runGit(src, ["pull", "--ff-only"], false).ok) {
+    console.error(
+      `${C4.red}\u2717${C4.reset} git pull failed \u2014 the branch may have diverged or you are offline. Resolve it manually, then retry.`
+    );
+    process.exit(1);
+  }
+  console.log(`${C4.dim}\u2192 npm install${C4.reset}`);
+  if (runNpm2(["install"], src) !== 0) {
+    console.error(`${C4.red}\u2717${C4.reset} npm install failed.`);
+    process.exit(1);
+  }
+  console.log(`${C4.dim}\u2192 npm run build${C4.reset}`);
+  if (runNpm2(["run", "build"], src) !== 0) {
+    console.error(`${C4.red}\u2717${C4.reset} Build failed.`);
+    process.exit(1);
+  }
+  console.log(`${C4.dim}\u2192 zam setup --force${C4.reset}`);
+  const setup = spawnSync2(
+    process.execPath,
+    [join20(src, "dist", "cli", "index.js"), "setup", "--force"],
+    { cwd: process.cwd(), stdio: "inherit" }
+  );
+  if (setup.status !== 0) {
+    console.warn(
+      `${C4.yellow}\u26A0${C4.reset} Skill refresh reported a problem \u2014 run '${C4.cyan}zam setup --force${C4.reset}' here manually.`
+    );
+  }
+  console.log(
+    `
+${C4.green}\u2713${C4.reset} Updated to ${C4.cyan}${versionAt(src)}${C4.reset}. Restart your agent client (e.g. Claude Code) to load the refreshed ${C4.cyan}/zam${C4.reset} skill.`
+  );
+}
+async function applyUpdate(opts) {
+  try {
+    const current = currentVersion();
+    const latest = await fetchLatestVersion(GITHUB_REPO);
+    const channel = getInstallChannel();
+    const decision = decideUpdate({
+      currentVersion: current,
+      latestVersion: latest,
+      channel
+    });
+    if (!decision.updateAvailable) {
+      console.log(
+        `${C4.green}\u2713${C4.reset} ZAM is up to date (${C4.cyan}${current}${C4.reset}).`
+      );
+      return;
+    }
+    console.log(
+      `${C4.yellow}\u2191${C4.reset} ${C4.bold}Update available${C4.reset}: ${C4.dim}${current}${C4.reset} \u2192 ${C4.cyan}${latest}${C4.reset} ${C4.dim}(${channel} install)${C4.reset}`
+    );
+    for (const step of planUpdate(decision)) {
+      console.log(`  ${C4.dim}\u2022${C4.reset} ${step.label}`);
+    }
+    if (channel === "direct") {
+      console.log(
+        `
+${C4.dim}This install updates through the desktop app's signed updater \u2014 open ZAM Desktop to install ${latest}.${C4.reset}`
+      );
+      return;
+    }
+    if (!opts.yes) {
+      const ok = await confirm3({
+        message: "Apply this update?",
+        default: true
+      });
+      if (!ok) {
+        console.log("Aborted.");
+        return;
+      }
+    }
+    console.log();
+    if (channel === "winget" || channel === "homebrew") {
+      if (!decision.command || !runShell(decision.command)) process.exit(1);
+      return;
+    }
+    applyDeveloperUpdate(opts.force ?? false);
+  } catch (err) {
+    console.error("Error:", err.message);
+    process.exit(1);
+  }
+}
+var updateCommand = new Command21("update").description(
+  "Update ZAM to the latest release (use `update check` to only check)"
+).option("-y, --yes", "Apply without confirmation").option(
+  "--force",
+  "Update even if the source checkout has uncommitted changes"
+).action(async (opts) => {
+  await applyUpdate(opts);
+}).addCommand(checkCmd);
 
 // src/cli/commands/whoami.ts
-import { Command as Command21 } from "commander";
-var whoamiCommand = new Command21("whoami").description("Show or set the default user identity").option("--set <id>", "Set the default user ID").option("--clear", "Remove the default user ID").option("--json", "Output as JSON").action(async (opts) => {
+import { Command as Command22 } from "commander";
+var whoamiCommand = new Command22("whoami").description("Show or set the default user identity").option("--set <id>", "Set the default user ID").option("--clear", "Remove the default user ID").option("--json", "Output as JSON").action(async (opts) => {
   await withDb(async (db) => {
     if (opts.set) {
       await setSetting(db, "user.id", opts.set);
@@ -9864,11 +10932,11 @@ var whoamiCommand = new Command21("whoami").description("Show or set the default
 
 // src/cli/commands/workspace.ts
 import { execSync as execSync6 } from "child_process";
-import { existsSync as existsSync20, writeFileSync as writeFileSync10 } from "fs";
-import { join as join20 } from "path";
-import { confirm as confirm3, input as input7 } from "@inquirer/prompts";
-import { Command as Command22 } from "commander";
-function runGit(cwd, args) {
+import { existsSync as existsSync21, writeFileSync as writeFileSync11 } from "fs";
+import { join as join21 } from "path";
+import { confirm as confirm4, input as input7 } from "@inquirer/prompts";
+import { Command as Command23 } from "commander";
+function runGit2(cwd, args) {
   try {
     return execSync6(`git ${args}`, {
       cwd,
@@ -9879,7 +10947,7 @@ function runGit(cwd, args) {
     throw new Error(`Git command failed: ${err.message}`);
   }
 }
-var workspaceCommand = new Command22("workspace").description(
+var workspaceCommand = new Command23("workspace").description(
   "Manage your ZAM learning workspace"
 );
 workspaceCommand.command("publish").description("Publish your local workspace sandbox to GitHub").action(async () => {
@@ -9898,7 +10966,7 @@ workspaceCommand.command("publish").description("Publish your local workspace sa
     );
     process.exit(1);
   }
-  if (!existsSync20(workspaceDir)) {
+  if (!existsSync21(workspaceDir)) {
     console.error(
       `\x1B[31m\u2717 Workspace directory does not exist: ${workspaceDir}\x1B[0m`
     );
@@ -9912,20 +10980,20 @@ Active workspace: \x1B[36m${workspaceDir}\x1B[0m`);
     );
     process.exit(1);
   }
-  const gitignorePath = join20(workspaceDir, ".gitignore");
-  if (!existsSync20(gitignorePath)) {
-    writeFileSync10(
+  const gitignorePath = join21(workspaceDir, ".gitignore");
+  if (!existsSync21(gitignorePath)) {
+    writeFileSync11(
       gitignorePath,
       "node_modules/\n.agent/\n.agents/\n.claude/\n.gemini/\n.goose/\n*.log\n",
       "utf8"
     );
   }
-  const hasGitRepo = existsSync20(join20(workspaceDir, ".git"));
+  const hasGitRepo = existsSync21(join21(workspaceDir, ".git"));
   if (!hasGitRepo) {
     console.log("Initializing local Git repository...");
-    runGit(workspaceDir, "init -b main");
-    runGit(workspaceDir, "add .");
-    runGit(
+    runGit2(workspaceDir, "init -b main");
+    runGit2(workspaceDir, "add .");
+    runGit2(
       workspaceDir,
       'commit -m "chore: initial workspace sandbox bootstrap"'
     );
@@ -9937,14 +11005,14 @@ Active workspace: \x1B[36m${workspaceDir}\x1B[0m`);
     message: "Choose a name for your GitHub repository:",
     default: "zam-personal"
   });
-  const isPrivate = await confirm3({
+  const isPrivate = await confirm4({
     message: "Should the repository be private?",
     default: true
   });
   const repoVisibility = isPrivate ? "--private" : "--public";
   if (hasCommand("gh")) {
     console.log("GitHub CLI detected! Automating repository creation...");
-    const proceedGh = await confirm3({
+    const proceedGh = await confirm4({
       message: "Would you like ZAM to create the repository using the GitHub CLI?",
       default: true
     });
@@ -9989,16 +11057,16 @@ Active workspace: \x1B[36m${workspaceDir}\x1B[0m`);
       console.log("Linking remote repository and pushing...");
       let hasOrigin = false;
       try {
-        runGit(workspaceDir, "remote get-url origin");
+        runGit2(workspaceDir, "remote get-url origin");
         hasOrigin = true;
       } catch {
       }
       if (hasOrigin) {
-        runGit(workspaceDir, `remote set-url origin ${githubUrl}`);
+        runGit2(workspaceDir, `remote set-url origin ${githubUrl}`);
       } else {
-        runGit(workspaceDir, `remote add origin ${githubUrl}`);
+        runGit2(workspaceDir, `remote add origin ${githubUrl}`);
       }
-      runGit(workspaceDir, "push -u origin main");
+      runGit2(workspaceDir, "push -u origin main");
       console.log(
         "\x1B[32m\u2713 Successfully linked and pushed to GitHub!\x1B[0m"
       );
@@ -10016,9 +11084,9 @@ Active workspace: \x1B[36m${workspaceDir}\x1B[0m`);
 // src/cli/index.ts
 var __dirname = dirname10(fileURLToPath5(import.meta.url));
 var pkg = JSON.parse(
-  readFileSync13(join21(__dirname, "..", "..", "package.json"), "utf-8")
+  readFileSync14(join22(__dirname, "..", "..", "package.json"), "utf-8")
 );
-var program = new Command23();
+var program = new Command24();
 program.name("zam").description(
   "The Symbiotic Learning Kernel: Elevating Human Intelligence through AI Collaboration."
 ).version(pkg.version);
@@ -10034,6 +11102,7 @@ program.addCommand(uiCommand);
 program.addCommand(bridgeCommand);
 program.addCommand(skillCommand);
 program.addCommand(monitorCommand);
+program.addCommand(observerCommand);
 program.addCommand(settingsCommand);
 program.addCommand(whoamiCommand);
 program.addCommand(connectorCommand);