@versatly/workgraph 0.3.0 → 1.1.0

package/dist/cli.js

@@ -1,17 +1,23 @@
 import {
+  agent_exports,
+  autonomy_daemon_exports,
   bases_exports,
   board_exports,
   clawdapus_exports,
   command_center_exports,
+  diagnostics_exports,
   integration_exports,
+  lens_exports,
   onboard_exports,
   search_qmd_adapter_exports,
   skill_exports,
   trigger_exports,
   workspace_exports
-} from "./chunk-E3QU5Y53.js";
+} from "./chunk-TOFSHG5S.js";
 import {
+  autonomy_exports,
   dispatch_exports,
+  gate_exports,
   graph_exports,
   ledger_exports,
   mcp_server_exports,
@@ -20,11 +26,14 @@ import {
   query_exports,
   registry_exports,
   store_exports,
-  thread_exports
-} from "./chunk-65ZMX2WM.js";
+  thread_audit_exports,
+  thread_exports,
+  trigger_engine_exports
+} from "./chunk-OTSECVE5.js";
 
 // src/cli.ts
 import fs from "fs";
+import os from "os";
 import path from "path";
 import { Command } from "commander";
 var DEFAULT_ACTOR = process.env.WORKGRAPH_AGENT || process.env.USER || "anonymous";
@@ -46,7 +55,7 @@ addWorkspaceOption(
   (targetPath, opts) => runCommand(
     opts,
     () => {
-      const workspacePath = path.resolve(targetPath || resolveWorkspacePath(opts));
+      const workspacePath = resolveInitTargetPath(targetPath, opts);
       const result = workspace_exports.initWorkspace(workspacePath, {
         name: opts.name,
         createTypeDirs: opts.typeDirs,
@@ -168,13 +177,17 @@ addWorkspaceOption(
   )
 );
 addWorkspaceOption(
-  threadCmd.command("claim <threadPath>").description("Claim a thread for this agent").option("-a, --actor <name>", "Agent name", DEFAULT_ACTOR).option("--json", "Emit structured JSON output")
+  threadCmd.command("claim <threadPath>").description("Claim a thread for this agent").option("-a, --actor <name>", "Agent name", DEFAULT_ACTOR).option("--lease-ttl-minutes <n>", "Claim lease TTL in minutes", "30").option("--json", "Emit structured JSON output")
 ).action(
   (threadPath, opts) => runCommand(
     opts,
     () => {
       const workspacePath = resolveWorkspacePath(opts);
-      return { thread: thread_exports.claim(workspacePath, threadPath, opts.actor) };
+      return {
+        thread: thread_exports.claim(workspacePath, threadPath, opts.actor, {
+          leaseTtlMinutes: Number.parseFloat(String(opts.leaseTtlMinutes))
+        })
+      };
     },
     (result) => [`Claimed: ${result.thread.path}`, `Owner: ${String(result.thread.fields.owner)}`]
   )
@@ -203,6 +216,18 @@ addWorkspaceOption(
     (result) => [`Done: ${result.thread.path}`]
   )
 );
+addWorkspaceOption(
+  threadCmd.command("reopen <threadPath>").description("Reopen a done/cancelled thread via compensating ledger op").option("-a, --actor <name>", "Agent name", DEFAULT_ACTOR).option("--reason <reason>", "Why the thread is being reopened").option("--json", "Emit structured JSON output")
+).action(
+  (threadPath, opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      return { thread: thread_exports.reopen(workspacePath, threadPath, opts.actor, opts.reason) };
+    },
+    (result) => [`Reopened: ${result.thread.path}`, `Status: ${String(result.thread.fields.status)}`]
+  )
+);
 addWorkspaceOption(
   threadCmd.command("block <threadPath>").description("Mark a thread blocked").requiredOption("-b, --blocked-by <dep>", "Dependency blocking this thread").option("-a, --actor <name>", "Agent name", DEFAULT_ACTOR).option("--reason <reason>", "Why it is blocked").option("--json", "Emit structured JSON output")
 ).action(
@@ -229,6 +254,63 @@ addWorkspaceOption(
     (result) => [`Unblocked: ${result.thread.path}`]
   )
 );
+addWorkspaceOption(
+  threadCmd.command("heartbeat [threadPath]").description("Refresh thread claim lease heartbeat (one thread or all active claims for actor)").option("-a, --actor <name>", "Agent name", DEFAULT_ACTOR).option("--ttl-minutes <n>", "Lease TTL in minutes", "30").option("--json", "Emit structured JSON output")
+).action(
+  (threadPath, opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      return thread_exports.heartbeatClaim(
+        workspacePath,
+        opts.actor,
+        threadPath,
+        {
+          ttlMinutes: Number.parseFloat(String(opts.ttlMinutes))
+        }
+      );
+    },
+    (result) => [
+      `Heartbeat actor: ${result.actor}`,
+      `Touched leases: ${result.touched.length}`,
+      ...result.touched.length > 0 ? result.touched.map((entry) => `- ${entry.threadPath} expires=${entry.expiresAt}`) : [],
+      ...result.skipped.length > 0 ? result.skipped.map((entry) => `SKIP ${entry.threadPath}: ${entry.reason}`) : []
+    ]
+  )
+);
+addWorkspaceOption(
+  threadCmd.command("reap-stale").description("Reopen/release stale claimed threads whose leases expired").option("-a, --actor <name>", "Agent name", DEFAULT_ACTOR).option("--limit <n>", "Max stale leases to reap this run").option("--json", "Emit structured JSON output")
+).action(
+  (opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      return thread_exports.reapStaleClaims(workspacePath, opts.actor, {
+        limit: opts.limit ? Number.parseInt(String(opts.limit), 10) : void 0
+      });
+    },
+    (result) => [
+      `Reaper actor: ${result.actor}`,
+      `Scanned stale leases: ${result.scanned}`,
+      `Reaped: ${result.reaped.length}`,
+      ...result.reaped.length > 0 ? result.reaped.map((entry) => `- ${entry.threadPath} (prev=${entry.previousOwner})`) : [],
+      ...result.skipped.length > 0 ? result.skipped.map((entry) => `SKIP ${entry.threadPath}: ${entry.reason}`) : []
+    ]
+  )
+);
+addWorkspaceOption(
+  threadCmd.command("leases").description("List claim leases and staleness state").option("--json", "Emit structured JSON output")
+).action(
+  (opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      const leases = thread_exports.listClaimLeaseStatus(workspacePath);
+      return { leases, count: leases.length };
+    },
+    (result) => result.leases.map((lease) => `${lease.stale ? "STALE" : "LIVE"} ${lease.owner} -> ${lease.target} expires=${lease.expiresAt}`)
+  )
+);
 addWorkspaceOption(
   threadCmd.command("decompose <threadPath>").description("Break a thread into sub-threads").requiredOption("--sub <specs...>", 'Sub-thread specs as "title|goal"').option("-a, --actor <name>", "Agent name", DEFAULT_ACTOR).option("--json", "Emit structured JSON output")
 ).action(
@@ -246,6 +328,58 @@ addWorkspaceOption(
     (result) => [`Created ${result.children.length} sub-thread(s).`]
   )
 );
+var agentCmd = program.command("agent").description("Track agent presence heartbeats");
+addWorkspaceOption(
+  agentCmd.command("heartbeat <name>").description("Create/update an agent presence heartbeat").option("-a, --actor <name>", "Actor writing the heartbeat", DEFAULT_ACTOR).option("--status <status>", "online | busy | offline", "online").option("--current-task <threadRef>", "Current task/thread slug for this agent").option("--capabilities <items>", "Comma-separated capability tags").option("--json", "Emit structured JSON output")
+).action(
+  (name, opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      return {
+        presence: agent_exports.heartbeat(workspacePath, name, {
+          actor: opts.actor,
+          status: normalizeAgentPresenceStatus(opts.status),
+          currentTask: opts.currentTask,
+          capabilities: csv(opts.capabilities)
+        })
+      };
+    },
+    (result) => [
+      `Heartbeat: ${String(result.presence.fields.name)} [${String(result.presence.fields.status)}]`,
+      `Last seen: ${String(result.presence.fields.last_seen)}`,
+      `Current task: ${String(result.presence.fields.current_task ?? "none")}`
+    ]
+  )
+);
+addWorkspaceOption(
+  agentCmd.command("list").description("List known agent presence entries").option("--json", "Emit structured JSON output")
+).action(
+  (opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      const agents = agent_exports.list(workspacePath);
+      return {
+        agents,
+        count: agents.length
+      };
+    },
+    (result) => {
+      if (result.agents.length === 0) return ["No agent presence entries found."];
+      return [
+        ...result.agents.map((entry) => {
+          const name = String(entry.fields.name ?? entry.path);
+          const status = String(entry.fields.status ?? "unknown");
+          const task = String(entry.fields.current_task ?? "none");
+          const lastSeen = String(entry.fields.last_seen ?? "unknown");
+          return `${name} [${status}] task=${task} last_seen=${lastSeen}`;
+        }),
+        `${result.count} agent(s)`
+      ];
+    }
+  )
+);
 var primitiveCmd = program.command("primitive").description("Manage primitive type definitions and instances");
 addWorkspaceOption(
   primitiveCmd.command("define <name>").description("Define a new primitive type").requiredOption("-d, --description <desc>", "Type description").option("-a, --actor <name>", "Agent name", DEFAULT_ACTOR).option("--fields <specs...>", 'Field definitions as "name:type"').option("--dir <directory>", "Storage directory override").option("--json", "Emit structured JSON output")
@@ -283,6 +417,8 @@ addWorkspaceOption(
     ]
   )
 );
+registerPrimitiveSchemaCommand("schema", "Show supported fields for a primitive type");
+registerPrimitiveSchemaCommand("fields", "Alias for schema");
 var basesCmd = program.command("bases").description("Generate Obsidian .base files from primitive-registry.yaml");
 addWorkspaceOption(
   basesCmd.command("sync-registry").description("Sync .workgraph/primitive-registry.yaml from active registry").option("--json", "Emit structured JSON output")
@@ -337,6 +473,46 @@ addWorkspaceOption(
     (result) => result.types.map((t) => `${t.name} (${t.directory}/) ${t.builtIn ? "[built-in]" : ""}`)
   )
 );
+function registerPrimitiveSchemaCommand(commandName, description) {
+  addWorkspaceOption(
+    primitiveCmd.command(`${commandName} <typeName>`).description(description).option("--json", "Emit structured JSON output")
+  ).action(
+    (typeName, opts) => runCommand(
+      opts,
+      () => {
+        const workspacePath = resolveWorkspacePath(opts);
+        const typeDef = registry_exports.getType(workspacePath, typeName);
+        if (!typeDef) {
+          throw new Error(`Unknown primitive type "${typeName}". Use \`workgraph primitive list\` to inspect available types.`);
+        }
+        const fields = Object.entries(typeDef.fields).map(([name, definition]) => ({
+          name,
+          type: definition.type,
+          required: definition.required === true,
+          default: definition.default,
+          enum: definition.enum ?? [],
+          description: definition.description ?? "",
+          template: definition.template ?? void 0,
+          pattern: definition.pattern ?? void 0,
+          refTypes: definition.refTypes ?? []
+        }));
+        return {
+          type: typeDef.name,
+          description: typeDef.description,
+          directory: typeDef.directory,
+          builtIn: typeDef.builtIn,
+          fields
+        };
+      },
+      (result) => [
+        `Type: ${result.type}`,
+        `Directory: ${result.directory}/`,
+        `Built-in: ${result.builtIn}`,
+        ...result.fields.map((field) => `- ${field.name}: ${field.type}${field.required ? " (required)" : ""}${field.description ? ` \u2014 ${field.description}` : ""}`)
+      ]
+    )
+  );
+}
 addWorkspaceOption(
   primitiveCmd.command("create <type> <title>").description("Create an instance of any primitive type").option("-a, --actor <name>", "Agent name", DEFAULT_ACTOR).option("--set <fields...>", 'Set fields as "key=value"').option("--body <text>", "Markdown body content", "").option("--json", "Emit structured JSON output")
 ).action(
@@ -353,7 +529,7 @@ addWorkspaceOption(
   )
 );
 addWorkspaceOption(
-  primitiveCmd.command("update <path>").description("Update an existing primitive instance").option("-a, --actor <name>", "Agent name", DEFAULT_ACTOR).option("--set <fields...>", 'Set fields as "key=value"').option("--body <text>", "Replace markdown body content").option("--body-file <path>", "Read markdown body content from file").option("--json", "Emit structured JSON output")
+  primitiveCmd.command("update <path>").description("Update an existing primitive instance").option("-a, --actor <name>", "Agent name", DEFAULT_ACTOR).option("--set <fields...>", 'Set fields as "key=value"').option("--etag <etag>", "Expected etag for optimistic concurrency").option("--body <text>", "Replace markdown body content").option("--body-file <path>", "Read markdown body content from file").option("--json", "Emit structured JSON output")
 ).action(
   (targetPath, opts) => runCommand(
     opts,
@@ -365,7 +541,9 @@ addWorkspaceOption(
         body = fs.readFileSync(path.resolve(opts.bodyFile), "utf-8");
       }
       return {
-        instance: store_exports.update(workspacePath, targetPath, updates, body, opts.actor)
+        instance: store_exports.update(workspacePath, targetPath, updates, body, opts.actor, {
+          expectedEtag: opts.etag
+        })
       };
     },
     (result) => [`Updated ${result.instance.type}: ${result.instance.path}`]
@@ -653,6 +831,26 @@ addWorkspaceOption(
     ]
   )
 );
+addWorkspaceOption(
+  ledgerCmd.command("reconcile").description("Audit thread files against ledger claims, leases, and dependency wiring").option("--fail-on-issues", "Exit non-zero when issues are found").option("--json", "Emit structured JSON output")
+).action(
+  (opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      const report = thread_audit_exports.reconcileThreadState(workspacePath);
+      if (opts.failOnIssues && !report.ok) {
+        throw new Error(`Ledger reconcile found ${report.issues.length} issue(s).`);
+      }
+      return report;
+    },
+    (result) => [
+      `Reconcile ok: ${result.ok}`,
+      `Threads: ${result.totalThreads} Claims: ${result.totalClaims} Leases: ${result.totalLeases}`,
+      ...result.issues.length > 0 ? result.issues.map((issue) => `${issue.kind}: ${issue.path} \u2014 ${issue.message}`) : ["No reconcile issues found."]
+    ]
+  )
+);
 addWorkspaceOption(
   ledgerCmd.command("seal").description("Rebuild ledger index + hash-chain state from ledger.jsonl").option("--json", "Emit structured JSON output")
 ).action(
@@ -674,6 +872,96 @@ addWorkspaceOption(
     ]
   )
 );
+addWorkspaceOption(
+  program.command("doctor").description("Diagnose vault health, warnings, and repairable issues").option("--fix", "Auto-repair safe issues (orphan links, stale claims/runs)").option("--stale-after-minutes <n>", "Threshold for stale claims/runs in minutes", "60").option("-a, --actor <name>", "Actor used for --fix mutations", DEFAULT_ACTOR).option("--json", "Emit structured JSON output")
+).action(
+  (opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      const staleAfterMinutes = Number.parseInt(String(opts.staleAfterMinutes), 10);
+      const safeStaleAfterMinutes = Number.isNaN(staleAfterMinutes) ? 60 : Math.max(1, staleAfterMinutes);
+      return diagnostics_exports.diagnoseVaultHealth(workspacePath, {
+        fix: !!opts.fix,
+        actor: opts.actor,
+        staleAfterMs: safeStaleAfterMinutes * 60 * 1e3
+      });
+    },
+    (result) => diagnostics_exports.renderDoctorReport(result)
+  )
+);
+addWorkspaceOption(
+  program.command("replay").description("Replay ledger events chronologically with typed filters").option("--type <type>", "create | update | transition").option("--actor <name>", "Filter by actor").option("--primitive <ref>", "Filter by primitive path/type substring").option("--since <iso>", "Filter events on/after ISO timestamp").option("--until <iso>", "Filter events on/before ISO timestamp").option("--no-color", "Disable colorized output").option("--json", "Emit structured JSON output")
+).action(
+  (opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      return diagnostics_exports.replayLedger(workspacePath, {
+        type: opts.type,
+        actor: opts.actor,
+        primitive: opts.primitive,
+        since: opts.since,
+        until: opts.until
+      });
+    },
+    (result) => diagnostics_exports.renderReplayText(result, {
+      color: opts.color !== false && !wantsJson(opts)
+    })
+  )
+);
+addWorkspaceOption(
+  program.command("viz").description("Render an ASCII wiki-link graph of primitives in this vault").option("--focus <slugOrPath>", "Center the graph on a specific node").option("--depth <n>", "Traversal depth from each root", "2").option("--top <n>", "When large, show top N most-connected roots", "10").option("--no-color", "Disable colorized output").option("--json", "Emit structured JSON output")
+).action(
+  (opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      const parsedDepth = Number.parseInt(String(opts.depth), 10);
+      const parsedTop = Number.parseInt(String(opts.top), 10);
+      return diagnostics_exports.visualizeVaultGraph(workspacePath, {
+        focus: opts.focus,
+        depth: Number.isNaN(parsedDepth) ? 2 : Math.max(1, parsedDepth),
+        top: Number.isNaN(parsedTop) ? 10 : Math.max(1, parsedTop),
+        color: opts.color !== false && !wantsJson(opts)
+      });
+    },
+    (result) => [
+      ...result.rendered.split("\n"),
+      "",
+      `Nodes: ${result.nodeCount}`,
+      `Edges: ${result.edgeCount}`,
+      ...result.focus ? [`Focus: ${result.focus}`] : []
+    ]
+  )
+);
+addWorkspaceOption(
+  program.command("stats").description("Show detailed vault statistics and graph/ledger health metrics").option("--json", "Emit structured JSON output")
+).action(
+  (opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      return diagnostics_exports.computeVaultStats(workspacePath);
+    },
+    (result) => diagnostics_exports.renderStatsReport(result)
+  )
+);
+addWorkspaceOption(
+  program.command("changelog").description("Generate a human-readable changelog from ledger events").requiredOption("--since <date>", "Include entries on/after this date (ISO-8601)").option("--until <date>", "Include entries on/before this date (ISO-8601)").option("--json", "Emit structured JSON output")
+).action(
+  (opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      return diagnostics_exports.generateLedgerChangelog(workspacePath, {
+        since: opts.since,
+        until: opts.until
+      });
+    },
+    (result) => diagnostics_exports.renderChangelogText(result)
+  )
+);
 addWorkspaceOption(
   program.command("command-center").description("Generate a markdown command center from workgraph state").option("-a, --actor <name>", "Agent name", DEFAULT_ACTOR).option("-o, --output <path>", "Output markdown path", "Command Center.md").option("-n, --recent <count>", "Recent ledger entries to include", "15").option("--json", "Emit structured JSON output")
 ).action(
@@ -766,6 +1054,57 @@ addWorkspaceOption(
     (result) => [`Captured intake: ${result.intake.path}`]
   )
 );
+var lensCmd = program.command("lens").description("Generate deterministic context lenses for situational awareness");
+addWorkspaceOption(
+  lensCmd.command("list").description("List built-in context lenses").option("--json", "Emit structured JSON output")
+).action(
+  (opts) => runCommand(
+    opts,
+    () => ({
+      lenses: lens_exports.listContextLenses()
+    }),
+    (result) => result.lenses.map((lens) => `lens://${lens.id} - ${lens.description}`)
+  )
+);
+addWorkspaceOption(
+  lensCmd.command("show <lensId>").description("Generate one context lens snapshot").option("-a, --actor <name>", "Actor identity for actor-scoped lenses", DEFAULT_ACTOR).option("--lookback-hours <hours>", "Lookback window in hours", "24").option("--stale-hours <hours>", "Stale threshold in hours", "24").option("--limit <n>", "Maximum items per section", "10").option("-o, --output <path>", "Write lens markdown to workspace-relative output path").option("--json", "Emit structured JSON output")
+).action(
+  (lensId, opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      const lensOptions = {
+        actor: opts.actor,
+        lookbackHours: parsePositiveNumberOption(opts.lookbackHours, "lookback-hours"),
+        staleHours: parsePositiveNumberOption(opts.staleHours, "stale-hours"),
+        limit: parsePositiveIntegerOption(opts.limit, "limit")
+      };
+      if (opts.output) {
+        return lens_exports.materializeContextLens(workspacePath, lensId, {
+          ...lensOptions,
+          outputPath: opts.output
+        });
+      }
+      return lens_exports.generateContextLens(workspacePath, lensId, lensOptions);
+    },
+    (result) => {
+      const metricSummary = Object.entries(result.metrics).map(([metric, value]) => `${metric}=${value}`).join(" ");
+      const sectionSummary = result.sections.map((section) => `${section.id}:${section.items.length}`).join(" ");
+      const lines = [
+        `Lens: ${result.lens}`,
+        `Generated: ${result.generatedAt}`,
+        ...result.actor ? [`Actor: ${result.actor}`] : [],
+        `Metrics: ${metricSummary || "none"}`,
+        `Sections: ${sectionSummary || "none"}`
+      ];
+      if (isMaterializedLensResult(result)) {
+        lines.push(`Saved markdown: ${result.outputPath}`);
+        return lines;
+      }
+      return [...lines, "", ...result.markdown.split("\n")];
+    }
+  )
+);
 addWorkspaceOption(
   program.command("query").description("Query primitive instances with multi-field filters").option("--type <type>", "Primitive type").option("--status <status>", "Status value").option("--owner <owner>", "Owner/actor value").option("--tag <tag>", "Tag filter").option("--text <text>", "Full-text contains filter").option("--path-includes <text>", "Path substring filter").option("--updated-after <iso>", "Updated at or after").option("--updated-before <iso>", "Updated at or before").option("--created-after <iso>", "Created at or after").option("--created-before <iso>", "Created at or before").option("--limit <n>", "Result limit").option("--offset <n>", "Result offset").option("--json", "Emit structured JSON output")
 ).action(
@@ -886,6 +1225,114 @@ addWorkspaceOption(
     ]
   )
 );
+addWorkspaceOption(
+  graphCmd.command("neighborhood <slug>").description("Find connected primitives within N wiki-link hops").option("--depth <n>", "Traversal depth (default: 2)", "2").option("--refresh", "Refresh graph index before querying").option("--json", "Emit structured JSON output")
+).action(
+  (slug, opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      return graph_exports.graphNeighborhoodQuery(workspacePath, slug, {
+        depth: parseNonNegativeIntOption(opts.depth, "depth"),
+        refresh: !!opts.refresh
+      });
+    },
+    (result) => [
+      `Center: ${result.center.path} (${result.center.exists ? "exists" : "missing"})`,
+      `Depth: ${result.depth}`,
+      `Connected nodes: ${result.connectedNodes.length}`,
+      `Edges in neighborhood: ${result.edges.length}`
+    ]
+  )
+);
+addWorkspaceOption(
+  graphCmd.command("impact <slug>").description("Analyze reverse-link impact for a primitive").option("--refresh", "Refresh graph index before querying").option("--json", "Emit structured JSON output")
+).action(
+  (slug, opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      return graph_exports.graphImpactAnalysis(workspacePath, slug, {
+        refresh: !!opts.refresh
+      });
+    },
+    (result) => [
+      `Target: ${result.target.path} (${result.target.exists ? "exists" : "missing"})`,
+      `Total references: ${result.totalReferences}`,
+      ...result.groups.map((group) => `${group.type}: ${group.referenceCount}`)
+    ]
+  )
+);
+addWorkspaceOption(
+  graphCmd.command("context <slug>").description("Assemble token-budgeted markdown context from graph neighborhood").option("--budget <tokens>", "Approx token budget (chars/4)", "2000").option("--refresh", "Refresh graph index before querying").option("--json", "Emit structured JSON output")
+).action(
+  (slug, opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      return graph_exports.graphContextAssembly(workspacePath, slug, {
+        budgetTokens: parsePositiveIntOption(opts.budget, "budget"),
+        refresh: !!opts.refresh
+      });
+    },
+    (result) => [
+      `Center: ${result.center.path}`,
+      `Budget: ${result.budgetTokens} tokens`,
+      `Used: ${result.usedTokens} tokens`,
+      `Sections: ${result.sections.length}`,
+      "",
+      result.markdown
+    ]
+  )
+);
+addWorkspaceOption(
+  graphCmd.command("edges <slug>").description("Show typed incoming/outgoing edges for one primitive").option("--refresh", "Refresh graph index before querying").option("--json", "Emit structured JSON output")
+).action(
+  (slug, opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      return graph_exports.graphTypedEdges(workspacePath, slug, {
+        refresh: !!opts.refresh
+      });
+    },
+    (result) => [
+      `Node: ${result.node.path} (${result.node.exists ? "exists" : "missing"})`,
+      `Outgoing edges: ${result.outgoing.length}`,
+      `Incoming edges: ${result.incoming.length}`,
+      ...result.outgoing.map((edge) => `OUT ${edge.type} ${edge.from} -> ${edge.to}`),
+      ...result.incoming.map((edge) => `IN  ${edge.type} ${edge.from} -> ${edge.to}`)
+    ]
+  )
+);
+addWorkspaceOption(
+  graphCmd.command("export <slug>").description("Export a markdown subgraph directory around a center primitive").option("--depth <n>", "Traversal depth (default: 2)", "2").option("--format <format>", "Export format (default: md)", "md").option("--output-dir <path>", "Output directory (default under .workgraph/graph-exports)").option("--refresh", "Refresh graph index before querying").option("--json", "Emit structured JSON output")
+).action(
+  (slug, opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      const format = String(opts.format ?? "md").trim().toLowerCase();
+      if (format !== "md") {
+        throw new Error(`Invalid --format "${opts.format}". Supported formats: md.`);
+      }
+      return graph_exports.graphExportSubgraph(workspacePath, slug, {
+        depth: parseNonNegativeIntOption(opts.depth, "depth"),
+        format,
+        outputDir: opts.outputDir,
+        refresh: !!opts.refresh
+      });
+    },
+    (result) => [
+      `Exported subgraph: ${result.outputDirectory}`,
+      `Center: ${result.center.path}`,
+      `Depth: ${result.depth}`,
+      `Nodes: ${result.exportedNodes.length}`,
+      `Edges: ${result.exportedEdgeCount}`,
+      `Manifest: ${result.manifestPath}`
+    ]
+  )
+);
 addWorkspaceOption(
   graphCmd.command("neighbors <nodePath>").description("Query incoming/outgoing wiki-link neighbors for one node").option("--refresh", "Refresh graph index before querying").option("--json", "Emit structured JSON output")
 ).action(
@@ -952,6 +1399,33 @@ addWorkspaceOption(
     (result) => result.parties.map((party) => `${party.id} [${party.roles.join(", ")}]`)
   )
 );
+var gateCmd = program.command("gate").description("Evaluate thread quality gates before claim");
+addWorkspaceOption(
+  gateCmd.command("check <threadRef>").description("Check policy-gate status for one thread").option("--json", "Emit structured JSON output")
+).action(
+  (threadRef, opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      return gate_exports.checkThreadGates(workspacePath, threadRef);
+    },
+    (result) => {
+      const header = [`Gate check for ${result.threadPath}: ${result.allowed ? "PASSED" : "FAILED"}`];
+      if (result.gates.length === 0) {
+        return [...header, "No gates configured."];
+      }
+      const details = result.gates.map((gate) => {
+        const failingRules = gate.rules.filter((rule) => !rule.ok);
+        const gateLabel = gate.gatePath ?? gate.gateRef;
+        if (failingRules.length === 0) {
+          return `[pass] ${gateLabel}`;
+        }
+        return `[fail] ${gateLabel} :: ${failingRules.map((rule) => rule.message).join("; ")}`;
+      });
+      return [...header, ...details];
+    }
+  )
+);
 var dispatchCmd = program.command("dispatch").description("Programmatic runtime dispatch contract");
 addWorkspaceOption(
   dispatchCmd.command("create <objective>").description("Create a new run dispatch request").option("-a, --actor <name>", "Actor", DEFAULT_ACTOR).option("--adapter <name>", "Adapter name", "cursor-cloud").option("--idempotency-key <key>", "Idempotency key").option("--json", "Emit structured JSON output")
@@ -972,6 +1446,21 @@ addWorkspaceOption(
     (result) => [`Run created: ${result.run.id} [${result.run.status}]`]
   )
 );
+addWorkspaceOption(
+  dispatchCmd.command("claim <threadRef>").description("Claim a thread after passing quality gates").option("-a, --actor <name>", "Actor", DEFAULT_ACTOR).option("--json", "Emit structured JSON output")
+).action(
+  (threadRef, opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      return dispatch_exports.claimThread(workspacePath, threadRef, opts.actor);
+    },
+    (result) => [
+      `Claimed thread: ${result.thread.path}`,
+      `Gates checked: ${result.gateCheck.gates.length}`
+    ]
+  )
+);
 addWorkspaceOption(
   dispatchCmd.command("create-execute <objective>").description("Create and execute a run with autonomous multi-agent coordination").option("-a, --actor <name>", "Actor", DEFAULT_ACTOR).option("--adapter <name>", "Adapter name", "cursor-cloud").option("--idempotency-key <key>", "Idempotency key").option("--agents <actors>", "Comma-separated agent identities for autonomous execution").option("--max-steps <n>", "Maximum scheduler steps", "200").option("--step-delay-ms <ms>", "Delay between scheduling steps", "25").option("--space <spaceRef>", "Restrict execution to one space").option("--no-checkpoint", "Skip automatic checkpoint generation after execution").option("--json", "Emit structured JSON output")
 ).action(
@@ -1089,6 +1578,65 @@ addWorkspaceOption(
     (result) => [`Stopped run: ${result.run.id} [${result.run.status}]`]
   )
 );
+addWorkspaceOption(
+  dispatchCmd.command("heartbeat <runId>").description("Heartbeat a running run lease and extend lease_expiry").option("-a, --actor <name>", "Actor", DEFAULT_ACTOR).option("--lease-minutes <n>", "Lease extension in minutes").option("--json", "Emit structured JSON output")
+).action(
+  (runId, opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      return {
+        run: dispatch_exports.heartbeat(workspacePath, runId, {
+          actor: opts.actor,
+          leaseMinutes: opts.leaseMinutes ? Number.parseInt(String(opts.leaseMinutes), 10) : void 0
+        })
+      };
+    },
+    (result) => [
+      `Heartbeated run: ${result.run.id}`,
+      `Lease expires: ${String(result.run.leaseExpires ?? "none")}`,
+      `Heartbeats: ${(result.run.heartbeats ?? []).length}`
+    ]
+  )
+);
+addWorkspaceOption(
+  dispatchCmd.command("reconcile").description("Requeue runs with expired leases").option("-a, --actor <name>", "Actor", DEFAULT_ACTOR).option("--json", "Emit structured JSON output")
+).action(
+  (opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      return dispatch_exports.reconcileExpiredLeases(workspacePath, opts.actor);
+    },
+    (result) => [
+      `Reconciled at: ${result.reconciledAt}`,
+      `Inspected runs: ${result.inspectedRuns}`,
+      `Requeued runs: ${result.requeuedRuns.length}`,
+      ...result.requeuedRuns.map((run) => `- ${run.id}`)
+    ]
+  )
+);
+addWorkspaceOption(
+  dispatchCmd.command("handoff <runId>").description("Create a structured run handoff to another agent").requiredOption("--to <agent>", "Target agent").requiredOption("--reason <text>", "Reason for handoff").option("-a, --actor <name>", "Actor", DEFAULT_ACTOR).option("--adapter <name>", "Adapter override for handoff run").option("--json", "Emit structured JSON output")
+).action(
+  (runId, opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      return dispatch_exports.handoffRun(workspacePath, runId, {
+        actor: opts.actor,
+        to: opts.to,
+        reason: opts.reason,
+        adapter: opts.adapter
+      });
+    },
+    (result) => [
+      `Handoff created: ${result.handoffRun.id} (from ${result.sourceRun.id})`,
+      `Target agent: ${result.handoffRun.actor}`,
+      `Objective: ${result.handoffRun.objective}`
+    ]
+  )
+);
 addWorkspaceOption(
   dispatchCmd.command("mark <runId>").description("Set run status transition explicitly").requiredOption("--status <status>", "running|succeeded|failed|cancelled").option("-a, --actor <name>", "Actor", DEFAULT_ACTOR).option("--output <text>", "Optional output payload").option("--error <text>", "Optional error payload").option("--json", "Emit structured JSON output")
 ).action(
@@ -1142,6 +1690,28 @@ addWorkspaceOption(
     ]
   )
 );
+var triggerEngineCmd = triggerCmd.command("engine").description("Run trigger engine");
+addWorkspaceOption(
+  triggerEngineCmd.command("run").description("Process trigger events once or continuously").option("-a, --actor <name>", "Actor", DEFAULT_ACTOR).option("--watch", "Continuously process new events").option("--poll-ms <ms>", "Poll interval in watch mode", "2000").option("--max-cycles <n>", "Maximum cycles before exiting").option("--entry-limit <n>", "Maximum ledger entries per cycle").option("--agents <actors>", "Comma-separated agents used when executing runs").option("--max-steps <n>", "Maximum adapter scheduler steps", "200").option("--step-delay-ms <ms>", "Adapter scheduler delay", "25").option("--space <spaceRef>", "Restrict run execution to one space").option("--stale-claim-minutes <m>", "Drift warning threshold for stale claims", "30").option("--no-execute-runs", "Do not execute dispatched runs").option("--json", "Emit structured JSON output")
+).action(
+  (opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      return trigger_engine_exports.runTriggerEngineCycle(workspacePath, {
+        actor: opts.actor
+      });
+    },
+    (result) => [
+      `Evaluated: ${result.evaluated} triggers`,
+      `Fired: ${result.fired}`,
+      `Errors: ${result.errors}`,
+      ...result.triggers.map(
+        (t) => `  ${t.triggerPath}: ${t.fired ? "FIRED" : "skipped"} (${t.reason})${t.error ? ` error: ${t.error}` : ""}`
+      )
+    ]
+  )
+);
 addWorkspaceOption(
   program.command("onboard").description("Guided agent-first workspace setup and starter artifacts").option("-a, --actor <name>", "Actor", DEFAULT_ACTOR).option("--spaces <list>", "Comma-separated space names").option("--no-demo-threads", "Skip starter onboarding threads").option("--json", "Emit structured JSON output")
 ).action(
@@ -1204,12 +1774,124 @@ addWorkspaceOption(
     (result) => [`Updated onboarding: ${result.onboarding.path} [${String(result.onboarding.fields.status)}]`]
   )
 );
+var autonomyCmd = program.command("autonomy").description("Run long-lived autonomous collaboration loops");
+addWorkspaceOption(
+  autonomyCmd.command("run").description("Run autonomy cycles (trigger engine + ready-thread execution)").option("-a, --actor <name>", "Actor", DEFAULT_ACTOR).option("--adapter <name>", "Dispatch adapter name", "cursor-cloud").option("--agents <actors>", "Comma-separated autonomous worker identities").option("--watch", "Run continuously instead of stopping when idle").option("--poll-ms <ms>", "Cycle poll interval", "2000").option("--max-cycles <n>", "Maximum cycles before exit").option("--max-idle-cycles <n>", "Idle cycles before exit in non-watch mode", "2").option("--max-steps <n>", "Maximum adapter scheduler steps", "200").option("--step-delay-ms <ms>", "Adapter scheduler delay", "25").option("--space <spaceRef>", "Restrict autonomy to one space").option("--stale-claim-minutes <m>", "Drift warning threshold", "30").option("--heartbeat-file <path>", "Write daemon heartbeat JSON to this path").option("--no-execute-triggers", "Disable trigger engine actions").option("--no-execute-ready-threads", "Disable ready-thread dispatch execution").option("--json", "Emit structured JSON output")
+).action(
+  (opts) => runCommand(
+    opts,
+    async () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      return autonomy_exports.runAutonomyLoop(workspacePath, {
+        actor: opts.actor,
+        adapter: opts.adapter,
+        agents: csv(opts.agents),
+        watch: !!opts.watch,
+        pollMs: Number.parseInt(String(opts.pollMs), 10),
+        maxCycles: opts.maxCycles ? Number.parseInt(String(opts.maxCycles), 10) : void 0,
+        maxIdleCycles: Number.parseInt(String(opts.maxIdleCycles), 10),
+        maxSteps: Number.parseInt(String(opts.maxSteps), 10),
+        stepDelayMs: Number.parseInt(String(opts.stepDelayMs), 10),
+        space: opts.space,
+        staleClaimMinutes: Number.parseInt(String(opts.staleClaimMinutes), 10),
+        heartbeatFile: opts.heartbeatFile,
+        executeTriggers: opts.executeTriggers,
+        executeReadyThreads: opts.executeReadyThreads
+      });
+    },
+    (result) => [
+      `Cycles: ${result.cycles.length}`,
+      `Final ready threads: ${result.finalReadyThreads}`,
+      `Final drift status: ${result.finalDriftOk ? "ok" : "issues"}`,
+      ...result.cycles.map(
+        (cycle) => `Cycle ${cycle.cycle}: ready=${cycle.readyThreads} trigger_actions=${cycle.triggerActions} run=${cycle.runStatus ?? "none"} drift_issues=${cycle.driftIssues}`
+      )
+    ]
+  )
+);
+var autonomyDaemonCmd = autonomyCmd.command("daemon").description("Manage autonomy process lifecycle (pid + heartbeat + logs)");
+addWorkspaceOption(
+  autonomyDaemonCmd.command("start").description("Start autonomy in detached daemon mode").option("-a, --actor <name>", "Actor", DEFAULT_ACTOR).option("--adapter <name>", "Dispatch adapter name", "cursor-cloud").option("--agents <actors>", "Comma-separated autonomous worker identities").option("--poll-ms <ms>", "Cycle poll interval", "2000").option("--max-cycles <n>", "Maximum cycles before daemon exits").option("--max-steps <n>", "Maximum adapter scheduler steps", "200").option("--step-delay-ms <ms>", "Adapter scheduler delay", "25").option("--space <spaceRef>", "Restrict autonomy to one space").option("--stale-claim-minutes <m>", "Drift warning threshold", "30").option("--log-path <path>", "Daemon log file path (workspace-relative)").option("--heartbeat-path <path>", "Heartbeat file path (workspace-relative)").option("--no-execute-triggers", "Disable trigger engine actions").option("--no-execute-ready-threads", "Disable ready-thread dispatch execution").option("--json", "Emit structured JSON output")
+).action(
+  (opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      return autonomy_daemon_exports.startAutonomyDaemon(workspacePath, {
+        cliEntrypointPath: process.argv[1] ?? path.resolve("bin/workgraph.js"),
+        actor: opts.actor,
+        adapter: opts.adapter,
+        agents: csv(opts.agents),
+        pollMs: Number.parseInt(String(opts.pollMs), 10),
+        maxCycles: opts.maxCycles ? Number.parseInt(String(opts.maxCycles), 10) : void 0,
+        maxSteps: Number.parseInt(String(opts.maxSteps), 10),
+        stepDelayMs: Number.parseInt(String(opts.stepDelayMs), 10),
+        space: opts.space,
+        staleClaimMinutes: Number.parseInt(String(opts.staleClaimMinutes), 10),
+        logPath: opts.logPath,
+        heartbeatPath: opts.heartbeatPath,
+        executeTriggers: opts.executeTriggers,
+        executeReadyThreads: opts.executeReadyThreads
+      });
+    },
+    (result) => [
+      `Daemon running: ${result.running}`,
+      ...result.pid ? [`PID: ${result.pid}`] : [],
+      `PID file: ${result.pidPath}`,
+      `Heartbeat: ${result.heartbeatPath}`,
+      `Log: ${result.logPath}`
+    ]
+  )
+);
+addWorkspaceOption(
+  autonomyDaemonCmd.command("status").description("Show autonomy daemon status").option("--json", "Emit structured JSON output")
+).action(
+  (opts) => runCommand(
+    opts,
+    () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      return autonomy_daemon_exports.readAutonomyDaemonStatus(workspacePath);
+    },
+    (result) => [
+      `Daemon running: ${result.running}`,
+      ...result.pid ? [`PID: ${result.pid}`] : [],
+      ...result.heartbeat ? [`Last heartbeat: ${result.heartbeat.ts}`] : ["Last heartbeat: none"],
+      `PID file: ${result.pidPath}`,
+      `Heartbeat: ${result.heartbeatPath}`,
+      `Log: ${result.logPath}`
+    ]
+  )
+);
+addWorkspaceOption(
+  autonomyDaemonCmd.command("stop").description("Stop autonomy daemon by PID").option("--signal <signal>", "Signal for graceful stop", "SIGTERM").option("--timeout-ms <ms>", "Graceful wait timeout", "5000").option("--json", "Emit structured JSON output")
+).action(
+  (opts) => runCommand(
+    opts,
+    async () => {
+      const workspacePath = resolveWorkspacePath(opts);
+      return autonomy_daemon_exports.stopAutonomyDaemon(workspacePath, {
+        signal: String(opts.signal),
+        timeoutMs: Number.parseInt(String(opts.timeoutMs), 10)
+      });
+    },
+    (result) => [
+      `Stopped: ${result.stopped}`,
+      `Previously running: ${result.previouslyRunning}`,
+      ...result.pid ? [`PID: ${result.pid}`] : [],
+      `Daemon running now: ${result.status.running}`
+    ]
+  )
+);
 var mcpCmd = program.command("mcp").description("Run Workgraph MCP server");
 addWorkspaceOption(
-  mcpCmd.command("serve").description("Serve stdio MCP tools/resources for this workspace").option("-a, --actor <name>", "Default actor for MCP write tools", DEFAULT_ACTOR).option("--read-only", "Disable all MCP write tools")
+  mcpCmd.command("serve").description("Serve stdio MCP tools/resources for this workspace").option("-a, --actor <name>", "Default actor for MCP write tools", DEFAULT_ACTOR).option("--read-only", "Disable all MCP write tools").option("--sse-port <port>", "Optional SSE event stream port").option("--sse-host <host>", "SSE bind host (default: 127.0.0.1)").option("--sse-path <path>", "SSE endpoint path (default: /events)").option("--sse-poll-ms <ms>", "Ledger poll interval for SSE stream (default: 250ms)").option("--sse-heartbeat-ms <ms>", "SSE heartbeat interval (default: 15000ms)")
 ).action(async (opts) => {
   const workspacePath = resolveWorkspacePath(opts);
   console.error(`Starting MCP server for workspace: ${workspacePath}`);
+  const ssePort = opts.ssePort !== void 0 ? Number.parseInt(String(opts.ssePort), 10) : void 0;
+  const ssePollMs = opts.ssePollMs !== void 0 ? Number.parseInt(String(opts.ssePollMs), 10) : void 0;
+  const sseHeartbeatMs = opts.sseHeartbeatMs !== void 0 ? Number.parseInt(String(opts.sseHeartbeatMs), 10) : void 0;
+  const sseEnabled = ssePort !== void 0 || opts.sseHost !== void 0 || opts.ssePath !== void 0;
   await mcp_server_exports.startWorkgraphMcpServer({
     workspacePath,
     defaultActor: opts.actor,
@@ -1218,15 +1900,51 @@ addWorkspaceOption(
 });
 await program.parseAsync();
 function addWorkspaceOption(command) {
-  return command.option("-w, --workspace <path>", "Workgraph workspace path").option("--vault <path>", "Alias for --workspace").option("--shared-vault <path>", "Shared vault path (e.g. mounted via Tailscale)");
+  return command.option("-w, --workspace <path>", "Workgraph workspace path").option("--vault <path>", "Alias for --workspace").option("--shared-vault <path>", "Shared vault path (e.g. mounted via Tailscale)").option("--dry-run", "Execute against a temporary workspace copy and discard changes");
 }
 function resolveWorkspacePath(opts) {
+  const originalWorkspacePath = resolveWorkspacePathBase(opts);
+  if (!opts.dryRun) return originalWorkspacePath;
+  if (opts.__dryRunWorkspace) return opts.__dryRunWorkspace;
+  const sandboxRoot = fs.mkdtempSync(path.join(os.tmpdir(), "workgraph-dry-run-"));
+  const sandboxWorkspace = path.join(sandboxRoot, "workspace");
+  if (fs.existsSync(originalWorkspacePath)) {
+    fs.cpSync(originalWorkspacePath, sandboxWorkspace, {
+      recursive: true,
+      force: true
+    });
+  } else {
+    fs.mkdirSync(sandboxWorkspace, { recursive: true });
+  }
+  opts.__dryRunWorkspaceRoot = sandboxRoot;
+  opts.__dryRunWorkspace = sandboxWorkspace;
+  opts.__dryRunOriginal = originalWorkspacePath;
+  return sandboxWorkspace;
+}
+function resolveWorkspacePathBase(opts) {
   const explicit = opts.workspace || opts.vault || opts.sharedVault;
   if (explicit) return path.resolve(explicit);
   if (process.env.WORKGRAPH_SHARED_VAULT) return path.resolve(process.env.WORKGRAPH_SHARED_VAULT);
   if (process.env.WORKGRAPH_PATH) return path.resolve(process.env.WORKGRAPH_PATH);
   return process.cwd();
 }
+function resolveInitTargetPath(targetPath, opts) {
+  const requestedPath = path.resolve(targetPath || resolveWorkspacePathBase(opts));
+  if (!opts.dryRun) return requestedPath;
+  if (opts.__dryRunWorkspace) return opts.__dryRunWorkspace;
+  const sandboxRoot = fs.mkdtempSync(path.join(os.tmpdir(), "workgraph-init-dry-run-"));
+  const sandboxWorkspace = path.join(sandboxRoot, path.basename(requestedPath));
+  if (fs.existsSync(requestedPath)) {
+    fs.cpSync(requestedPath, sandboxWorkspace, {
+      recursive: true,
+      force: true
+    });
+  }
+  opts.__dryRunWorkspaceRoot = sandboxRoot;
+  opts.__dryRunWorkspace = sandboxWorkspace;
+  opts.__dryRunOriginal = requestedPath;
+  return sandboxWorkspace;
+}
 function parseSetPairs(pairs) {
   const fields = {};
   for (const pair of pairs) {
@@ -1279,6 +1997,37 @@ function parseScalar(value) {
     return value;
   }
 }
+function parsePositiveIntOption(value, name) {
+  const parsed = Number.parseInt(String(value ?? ""), 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`Invalid --${name} value "${String(value)}". Expected a positive integer.`);
+  }
+  return parsed;
+}
+function parsePositiveNumberOption(value, optionName) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`Invalid --${optionName}. Expected a positive number.`);
+  }
+  return parsed;
+}
+function parseNonNegativeIntOption(value, name) {
+  const parsed = Number.parseInt(String(value ?? ""), 10);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    throw new Error(`Invalid --${name} value "${String(value)}". Expected a non-negative integer.`);
+  }
+  return parsed;
+}
+function parsePositiveIntegerOption(value, optionName) {
+  const parsed = Number.parseInt(String(value), 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`Invalid --${optionName}. Expected a positive integer.`);
+  }
+  return parsed;
+}
+function isMaterializedLensResult(value) {
+  return typeof value.outputPath === "string";
+}
 function normalizeRunStatus(status) {
   const normalized = String(status).toLowerCase();
   if (normalized === "running" || normalized === "succeeded" || normalized === "failed" || normalized === "cancelled") {
@@ -1286,6 +2035,13 @@ function normalizeRunStatus(status) {
   }
   throw new Error(`Invalid run status "${status}". Expected running|succeeded|failed|cancelled.`);
 }
+function normalizeAgentPresenceStatus(status) {
+  const normalized = String(status).toLowerCase();
+  if (normalized === "online" || normalized === "busy" || normalized === "offline") {
+    return normalized;
+  }
+  throw new Error(`Invalid agent status "${status}". Expected online|busy|offline.`);
+}
 function normalizeOnboardingStatus(status) {
   const normalized = String(status).toLowerCase();
   if (normalized === "active" || normalized === "paused" || normalized === "completed") {
@@ -1301,19 +2057,45 @@ function wantsJson(opts) {
 async function runCommand(opts, action, renderText) {
   try {
     const result = await action();
+    const dryRunMetadata = opts.dryRun ? {
+      dryRun: true,
+      targetWorkspace: opts.__dryRunOriginal ?? resolveWorkspacePathBase(opts),
+      sandboxWorkspace: opts.__dryRunWorkspace
+    } : {};
     if (wantsJson(opts)) {
-      console.log(JSON.stringify({ ok: true, data: result }, null, 2));
+      console.log(JSON.stringify({ ok: true, ...dryRunMetadata, data: result }, null, 2));
       return;
     }
+    if (opts.dryRun) {
+      console.log(
+        [
+          "[dry-run] Executed against sandbox workspace and discarded changes.",
+          `Target: ${opts.__dryRunOriginal ?? resolveWorkspacePathBase(opts)}`,
+          `Sandbox: ${opts.__dryRunWorkspace ?? "n/a"}`
+        ].join(" ")
+      );
+    }
     const lines = renderText(result);
     for (const line of lines) console.log(line);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     if (wantsJson(opts)) {
-      console.error(JSON.stringify({ ok: false, error: message }, null, 2));
+      console.error(JSON.stringify({ ok: false, dryRun: !!opts.dryRun, error: message }, null, 2));
     } else {
       console.error(`Error: ${message}`);
     }
+    cleanupDryRunSandbox(opts);
     process.exit(1);
+  } finally {
+    cleanupDryRunSandbox(opts);
+  }
+}
+function cleanupDryRunSandbox(opts) {
+  if (!opts.dryRun || !opts.__dryRunWorkspaceRoot) return;
+  if (fs.existsSync(opts.__dryRunWorkspaceRoot)) {
+    fs.rmSync(opts.__dryRunWorkspaceRoot, { recursive: true, force: true });
   }
+  delete opts.__dryRunWorkspaceRoot;
+  delete opts.__dryRunWorkspace;
+  delete opts.__dryRunOriginal;
 }