@corvio/cli 0.1.0-beta.14 → 0.1.0-beta.15

package/README.md

@@ -7,15 +7,16 @@ npm install --global @corvio/cli@beta
 export CORVIO_API_KEY='cvu_...'
 corvio auth status
 corvio agents connect --provider codex --project . --json
+corvio collaboration status --json --no-input
 corvio ask --prompt 'Summarize recurring launch risks' --json
 corvio files upload --file ./research.pdf --json
 corvio sync init --dir ./knowledge --root-node-id <node_id> --json
 corvio update check --json
 ```
 
-When no environment key is configured, run `corvio auth login`. Login creates one user-level `cvu_` control-plane credential; it does not freeze the browser's current Workspace. Run `corvio agents connect --project .` from the project you want to expose. The command verifies the selected Codex, Claude Code, or Copilot host before server mutation, then idempotently creates or restores the Agent for that provider/device/project binding, grants current/future Workspace coverage under live membership/role and ACL limits, saves the one-time `cvg_` in a `0600` multi-binding registry, and starts that project's listener. Another project gets another Agent. Ordinary data commands prefer the binding whose root contains the current directory. Use `corvio workspaces use`, `--workspace`, and `--agent` as explicit routing/reproducibility controls. Legacy Workspace-bound `cvk_`, `cvg_`, and version-1 credential files remain compatible and are never widened. Local sync stores only credential-free handles and revision/hash baselines in `.corvio/state.json`; Markdown lives below `corvio_docs/`, and conflicts require explicit resolution. Update checks compare npm's published `beta` tag with the API compatibility policy but never self-install. See [the Corvio CLI guide](https://corvio.ai/developers/cli) for the full command and receipt contract.
+When no environment key is configured, run `corvio auth login`. Login creates one user-level `cvu_` control-plane credential; it does not freeze the browser's current Workspace. Run `corvio agents connect --project .` from the project you want to expose. The command verifies the selected Codex, Claude Code, or Copilot host before server mutation, then idempotently creates or restores the Agent for that provider/device/project binding, grants current/future Workspace coverage under live membership/role and ACL limits, saves the one-time `cvg_` in a `0600` multi-binding registry, and starts that project's listener. `corvio collaboration status` then checks a separate foreground requirement: the current host must also discover the official Skill at the live server contract version. A listener receives inbound `@Agent` work; it does not make an unrelated foreground coding session collaborate automatically. Another project gets another Agent. Ordinary data commands prefer the binding whose root contains the current directory. Use `corvio workspaces use`, `--workspace`, and `--agent` as explicit routing/reproducibility controls. Legacy Workspace-bound `cvk_`, `cvg_`, and version-1 credential files remain compatible and are never widened. Local sync stores only credential-free handles and revision/hash baselines in `.corvio/state.json`; Markdown lives below `corvio_docs/`, and conflicts require explicit resolution. Update checks compare npm's published `beta` tag with the API compatibility policy but never self-install. See [the Corvio CLI guide](https://corvio.ai/developers/cli) for the full command and receipt contract.
 
-The CLI rejects unknown/duplicate options and malformed integer bounds before network access. Normal API calls have a bounded timeout (`CORVIO_REQUEST_TIMEOUT_MS`, maximum ten minutes); only reads, explicit idempotency contracts, revision guards, and other owner-declared safe operations retry automatically. Document updates preflight the current revision when `--expected-revision` is omitted. When the executing principal is a connected Agent, `docs update` also requires `--change-summary`, creates a visible document-level comment after the guarded write, and returns its receipt; a comment failure is reported as a partial effect rather than silent success. Downloads, uploads, and Markdown pulls verify SHA-256 receipts before replacing local files; local writes are atomic, remote default filenames cannot escape the current directory, and Sync refuses symbolic-link traversal while checkpointing each successful push.
+The CLI rejects unknown/duplicate options and malformed integer bounds before network access. Normal API calls have a bounded timeout (`CORVIO_REQUEST_TIMEOUT_MS`, maximum ten minutes); only reads, explicit idempotency contracts, revision guards, and other owner-declared safe operations retry automatically. Document updates preflight the current revision when `--expected-revision` is omitted. When the executing principal is a connected Agent, `docs update` also requires `--change-summary`, creates a visible document-level comment after the guarded write, and returns its receipt; a comment failure is reported as a partial effect rather than silent success. When a Corvio document or comment supplied the task, use `corvio agent closeout` to return the verified outcome, optionally resolve the thread, and read both document and thread back. Downloads, uploads, and Markdown pulls verify SHA-256 receipts before replacing local files; local writes are atomic, remote default filenames cannot escape the current directory, and Sync refuses symbolic-link traversal while checkpointing each successful push.
 
 ## Project Agent collaboration
 
@@ -25,7 +26,7 @@ Connect the current project with the user credential. User and Agent credentials
 corvio agents connect --provider codex --project . --json
 ```
 
-Without `--display-name`, connect derives a provider-aware project name from the authenticated user, such as `Ada Codex · billing-service`; Settings remains the rename owner. The receipt distinguishes `Configured`, `CLI Ready`, `Listening`, and `Offline`, and includes the stable Agent, opaque project binding, Workspace scope, host permission/trigger policy, and Settings link. The default `workspace_write` profile uses the provider's native sandbox. `owner_only` is the safe trigger default. Allowing Workspace members to invoke the local project or granting unrestricted host access requires explicit `--yes`.
+Without `--display-name`, connect derives a provider-aware project name from the authenticated user, such as `Ada Codex · billing-service`; Settings remains the rename owner. The receipt distinguishes `Configured`, `CLI Ready`, `Listening`, `Offline`, and `Foreground collaboration ready`, and includes the stable Agent, opaque project binding, Workspace scope, host permission/trigger policy, Skill status, and Settings link. The default `workspace_write` profile uses the provider's native sandbox. `owner_only` is the safe trigger default. Allowing Workspace members to invoke the local project or granting unrestricted host access requires explicit `--yes`.
 
 The listener first runs a read-only provider planning pass, then asks Corvio Query for exact origin-document and collaboration context. `local_project` work runs inside the bound project; online document writes remain Query/Writer-owned. The provider consumes the Query result before replying, and completion records exact event/lease/question/comment lineage plus provider, project fingerprint, claimed files/checks, and observed Git working-tree state. A custom handler remains available for advanced adapters:
 

package/dist/cli.js

@@ -39,13 +39,14 @@ import {
   agentCredentialPath,
 } from "./core.js";
 
-const VERSION = "0.1.0-beta.14";
+const VERSION = "0.1.0-beta.15";
 const DEFAULT_API_BASE = "https://api.corvio.ai/v1";
 const DEFAULT_APP_BASE = "https://corvio.ai";
 const USER_AGENT = `corvio-cli/${VERSION}`;
 const MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
 const MAX_SYNC_FILES = 2_000;
 const MAX_MARKDOWN_CHARACTERS = 120_000;
+const CORVIO_SKILL_INSTALL_COMMAND = "npx skills add https://corvio.ai/developers/skills/corvio-operate-workspace/corvio-operate-workspace.zip";
 const GLOBAL_OPTIONS = Object.freeze([
   "api-base",
   "workspace",
@@ -67,6 +68,7 @@ const COMMAND_OPTIONS = Object.freeze({
   "workspaces:use": ["id"],
   "workspaces:create": ["name", "kind", "description", "idempotency-key"],
   "capabilities:": [],
+  "collaboration:status": ["project", "provider"],
   "ask:": ["prompt", "conversation-id", "sources", "allow-actions", "context-file", "idempotency-key"],
   "agents:list": ["include-revoked"],
   "agents:connect": [
@@ -85,6 +87,7 @@ const COMMAND_OPTIONS = Object.freeze({
   "agent:comment": ["document-id", "body", "selection-file", "start-new-chain", "idempotency-key"],
   "agent:reply": ["document-id", "id", "body", "source-event-id", "source-event-lease-token", "start-new-chain", "idempotency-key"],
   "agent:status": ["document-id", "id", "status"],
+  "agent:closeout": ["document-id", "thread-id", "body", "status", "idempotency-key"],
   "agent:run": ["once", "handler", "provider", "worker-id", "lease-seconds", "wait-seconds", "sources", "project"],
   "questions:list": ["limit", "cursor", "conversation-id"],
   "questions:get": ["id"],
@@ -123,9 +126,10 @@ Usage:
   corvio auth login|status|logout
   corvio workspaces list|use|current|create [id]
   corvio capabilities
+  corvio collaboration status [--project <path>] [--provider codex|claude_code|copilot]
   corvio ask --prompt <text> [--conversation-id <id>] [--allow-actions]
   corvio agents list|connect|create|update|rotate [id]
-  corvio agent claim|renew|complete|fail|comments|comment|reply|status|run [id]
+  corvio agent claim|renew|complete|fail|comments|comment|reply|status|closeout|run [id]
   corvio questions list|get [id]
   corvio conversations list|get [id]
   corvio search <query>
@@ -151,13 +155,14 @@ const COMMAND_HELP = Object.freeze({
   auth: `Usage: corvio auth login|status|logout\n\nAuthenticate with a user-level device link, inspect the current principal, or revoke the stored credential.`,
   workspaces: `Usage:\n  corvio workspaces list\n  corvio workspaces use <workspace-id>\n  corvio workspaces current\n  corvio workspaces create --name <name> [--kind personal|team]\n\nWorkspace status and blocked capability reasons are returned with each item.`,
   capabilities: `Usage: corvio capabilities [--json]\n\nShow live API resources, principal scopes, selected Workspace status, and CLI compatibility.`,
+  collaboration: `Usage:\n  corvio collaboration status [--project <path>] [--provider codex|claude_code|copilot]\n\nVerify that the current project has a bound Corvio Agent, the official collaboration Skill is discoverable at the live contract version, and the inbound listener state is reported separately. This is the foreground work-loop readiness check; a listening process alone is not enough.`,
   ask: `Usage: corvio ask --prompt <text> [--conversation-id <id>] [--sources workspace,web,memory] [--allow-actions] [--context-file <json>] [--idempotency-key <key>]`,
-  agents: `Usage:\n  corvio agents list\n  corvio agents connect [--provider codex|claude_code|copilot] [--project <path>] [--permission-profile read_only|workspace_write|danger_full_access] [--trigger-policy owner_only|workspace_members] [--display-name <name>] [--recover-credential] [--no-listen]\n  corvio agents create --handle <handle> --display-name <name> [--provider codex|claude_code|copilot|custom] [--permissions read,comment,edit]\n  corvio agents update <id> [--display-name <name>] [--status active|paused|revoked] [--permissions <list>]\n  corvio agents rotate <id>\n\n'connect' binds the current Git project (or --project path) to one stable personal Agent. Repeating it is idempotent; another project creates another Agent. The default workspace_write profile is limited by the provider's native sandbox. owner_only is the safe trigger default. Secrets and absolute project paths stay local.`,
-  agent: `Usage:\n  corvio agent claim [--worker-id <id>] [--wait-seconds <0-30>]\n  corvio agent renew <event-id> --lease-token <token> [--lease-seconds <30-900>]\n  corvio agent complete <event-id> --lease-token <token> [--result-file <json>]\n  corvio agent fail <event-id> --lease-token <token> --error <message>\n  corvio agent mentions --document-id <id> [--query <name>]\n  corvio agent comments --document-id <id>\n  corvio agent comment --document-id <id> --body <text> [--selection-file <json>] [--start-new-chain] [--idempotency-key <key>]\n  corvio agent reply <thread-id> --document-id <id> --body <text> [--source-event-id <id> --source-event-lease-token <token>|--start-new-chain] [--idempotency-key <key>]\n  corvio agent status <thread-id> --document-id <id> --status open|resolved\n  corvio agent run [--provider codex|claude_code|copilot|custom] [--handler <executable>] [--agent <id>] [--once]\n\nUse mentions before commenting when the target is uncertain; aliases resolve to stable user or Agent IDs and ambiguity fails closed. Agent-to-Agent comments require either a claimed source event or explicit --start-new-chain. The runner iteratively exchanges origin-scoped evidence with Corvio Query/Writer, then invokes the bound provider inside its local project. Local code changes use the recorded provider permission profile; complex Corvio document changes belong to Query/Writer. Provider children never receive Corvio credentials.`,
+  agents: `Usage:\n  corvio agents list\n  corvio agents connect [--provider codex|claude_code|copilot] [--project <path>] [--permission-profile read_only|workspace_write|danger_full_access] [--trigger-policy owner_only|workspace_members] [--display-name <name>] [--recover-credential] [--no-listen]\n  corvio agents create --handle <handle> --display-name <name> [--provider codex|claude_code|copilot|custom] [--permissions read,comment,edit]\n  corvio agents update <id> [--display-name <name>] [--status active|paused|revoked] [--permissions <list>]\n  corvio agents rotate <id>\n\n'connect' binds the current Git project (or --project path) to one stable personal Agent. Repeating it is idempotent; another project creates another Agent. It reports provider/CLI, listener, and foreground Skill readiness separately; run corvio collaboration status after installing or refreshing the Skill. The default workspace_write profile is limited by the provider's native sandbox. owner_only is the safe trigger default. Secrets and absolute project paths stay local.`,
+  agent: `Usage:\n  corvio agent claim [--worker-id <id>] [--wait-seconds <0-30>]\n  corvio agent renew <event-id> --lease-token <token> [--lease-seconds <30-900>]\n  corvio agent complete <event-id> --lease-token <token> [--result-file <json>]\n  corvio agent fail <event-id> --lease-token <token> --error <message>\n  corvio agent mentions --document-id <id> [--query <name>]\n  corvio agent comments --document-id <id>\n  corvio agent comment --document-id <id> --body <text> [--selection-file <json>] [--start-new-chain] [--idempotency-key <key>]\n  corvio agent reply <thread-id> --document-id <id> --body <text> [--source-event-id <id> --source-event-lease-token <token>|--start-new-chain] [--idempotency-key <key>]\n  corvio agent status <thread-id> --document-id <id> --status open|resolved\n  corvio agent closeout --document-id <id> [--thread-id <id>] --body <verified-result> [--status open|resolved] [--idempotency-key <key>]\n  corvio agent run [--provider codex|claude_code|copilot|custom] [--handler <executable>] [--agent <id>] [--once]\n\nUse mentions before commenting when the target is uncertain; aliases resolve to stable user or Agent IDs and ambiguity fails closed. Use closeout when a Corvio document or comment owned the task: it returns the verified result to that surface and reads document/comments back. Agent-to-Agent comments require either a claimed source event or explicit --start-new-chain. The runner iteratively exchanges origin-scoped evidence with Corvio Query/Writer, then invokes the bound provider inside its local project. Local code changes use the recorded provider permission profile; complex Corvio document changes belong to Query/Writer. Provider children never receive Corvio credentials.`,
   questions: `Usage:\n  corvio questions list [--limit <n>] [--cursor <cursor>] [--conversation-id <id>]\n  corvio questions get <question-id>`,
   conversations: `Usage:\n  corvio conversations list [--limit <n>] [--cursor <cursor>]\n  corvio conversations get <conversation-id>`,
   search: `Usage: corvio search <query> [--limit <n>] [--page-id <id>] [--node-id <id>]`,
-  docs: `Usage:\n  corvio docs list [--limit <n>] [--cursor <cursor>] [--lifecycle active|archived]\n  corvio docs get <id> [--output <path>]\n  corvio docs create --title <title> [--file <path>|--markdown <text>] [--parent-node-id <id>] [--idempotency-key <key>]\n  corvio docs update <id> [--title <title>] [--file <path>|--markdown <text>] [--expected-revision <n>] [--change-summary <text>]\n  corvio docs move <id> --parent-node-id <id>\n  corvio docs archive <id> --yes\n  corvio docs restore <id> --yes\n  corvio docs share <id> --yes [--display-name <name>]\n  corvio docs open <id>\n\nDirect document commands operate on canonical Page/Markdown. Use \`corvio ask --allow-actions\` for Spreadsheet, Presentation, Code, HTML Artifact, or semantic organization. Agent-authenticated document updates require --change-summary and create a visible document-level comment after the guarded update. When a document/comment is the task owner, use \`corvio agent comments|reply|status\` to return verified work to that same collaboration surface.`,
+  docs: `Usage:\n  corvio docs list [--limit <n>] [--cursor <cursor>] [--lifecycle active|archived]\n  corvio docs get <id> [--output <path>]\n  corvio docs create --title <title> [--file <path>|--markdown <text>] [--parent-node-id <id>] [--idempotency-key <key>]\n  corvio docs update <id> [--title <title>] [--file <path>|--markdown <text>] [--expected-revision <n>] [--change-summary <text>]\n  corvio docs move <id> --parent-node-id <id>\n  corvio docs archive <id> --yes\n  corvio docs restore <id> --yes\n  corvio docs share <id> --yes [--display-name <name>]\n  corvio docs open <id>\n\nDirect document commands operate on canonical Page/Markdown. Use \`corvio ask --allow-actions\` for Spreadsheet, Presentation, Code, HTML Artifact, or semantic organization. Agent-authenticated document updates require --change-summary and create a visible document-level comment after the guarded update. When a document/comment is the task owner, use \`corvio agent closeout\` to return verified work to that same collaboration surface and read it back.`,
   projects: `Usage:\n  corvio projects list [--limit <n>]\n  corvio projects create --title <title> [--idempotency-key <key>]\n\nProjects are durable grouping owners in the Corvio Docs tree. Reuse a matching Project instead of creating one ceremonial Project per file. 'corvio folders' is an alias.`,
   files: `Usage:\n  corvio files list [--limit <n>]\n  corvio files get <id>\n  corvio files download <id> [--output <path>]\n  corvio files upload --file <path> [--mime-type <type>]\n  corvio files organize <id> --instruction <text> --yes [--target-root-node-id <id>]\n  corvio files open <id>`,
   sync: `Usage:\n  corvio sync init --root-node-id <id> [--dir <path>] [--name <name>]\n  corvio sync status|plan|pull [--dir <path>]\n  corvio sync push --yes [--dir <path>]\n  corvio sync resolve --conflict-id <id> --strategy use-remote|keep-local --yes [--dir <path>]`,
@@ -185,6 +190,7 @@ function normalizeInvocation(command, action) {
     projects: "list",
     files: "list",
     agents: "list",
+    collaboration: "status",
     agent: "claim",
     sync: "status",
     update: "check",
@@ -650,6 +656,141 @@ async function capabilities(options) {
   }, { json: options.json });
 }
 
+async function codexPluginGuidanceCandidates(codexHome) {
+  const cacheRoot = join(codexHome, "plugins", "cache");
+  const listDirectories = async (directory) => {
+    try {
+      return (await readdir(directory, { withFileTypes: true }))
+        .filter((entry) => entry.isDirectory())
+        .slice(0, 256)
+        .map((entry) => entry.name);
+    } catch (error) {
+      if (["ENOENT", "ENOTDIR", "EACCES"].includes(error?.code)) return [];
+      throw error;
+    }
+  };
+  const candidates = [];
+  for (const marketplace of await listDirectories(cacheRoot)) {
+    const marketplaceRoot = join(cacheRoot, marketplace);
+    for (const plugin of await listDirectories(marketplaceRoot)) {
+      const pluginRoot = join(marketplaceRoot, plugin);
+      for (const version of await listDirectories(pluginRoot)) {
+        candidates.push({
+          scope: "codex_plugin_cache",
+          path: join(pluginRoot, version, "skills", "corvio-operate-workspace", "SKILL.md"),
+        });
+      }
+    }
+  }
+  return candidates;
+}
+
+async function inspectCollaborationGuidance(provider, projectRoot, expectedContractVersion) {
+  const candidates = [
+    { scope: "project_agents", path: join(projectRoot, ".agents", "skills", "corvio-operate-workspace", "SKILL.md") },
+    { scope: "user_agents", path: join(homedir(), ".agents", "skills", "corvio-operate-workspace", "SKILL.md") },
+  ];
+  if (provider === "codex") {
+    const codexHome = String(process.env.CODEX_HOME || join(homedir(), ".codex"));
+    candidates.push({
+      scope: "user_codex",
+      path: join(codexHome, "skills", "corvio-operate-workspace", "SKILL.md"),
+    });
+    candidates.push(...await codexPluginGuidanceCandidates(codexHome));
+  }
+  if (provider === "claude_code") {
+    candidates.push(
+      { scope: "project_claude", path: join(projectRoot, ".claude", "skills", "corvio-operate-workspace", "SKILL.md") },
+      {
+        scope: "user_claude",
+        path: join(String(process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude")), "skills", "corvio-operate-workspace", "SKILL.md"),
+      },
+    );
+  }
+  const found = [];
+  for (const candidate of candidates) {
+    try {
+      const source = await readFile(candidate.path, "utf8");
+      if (!/^name:\s*corvio-operate-workspace\s*$/m.test(source)) continue;
+      found.push({
+        scope: candidate.scope,
+        current: Boolean(expectedContractVersion)
+          && source.includes(`contract version \`${expectedContractVersion}\``),
+      });
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+  }
+  const current = found.filter((item) => item.current);
+  const status = !expectedContractVersion
+    ? "contract_unavailable"
+    : current.length
+      ? "ready"
+      : found.length
+        ? "stale"
+        : "missing";
+  return {
+    status,
+    expected_contract_version: expectedContractVersion || null,
+    discovered_scopes: found.map((item) => item.scope),
+    current_scopes: current.map((item) => item.scope),
+    install_command: status === "missing" || status === "stale" ? CORVIO_SKILL_INSTALL_COMMAND : null,
+  };
+}
+
+async function collaborationStatus(options) {
+  const projectRoot = await findProjectRoot(options.project);
+  const credential = await readAgentCredential(process.env, {
+    required: false,
+    agentId: String(options.agent || "").trim() || null,
+    projectRoot,
+    fallbackToActive: false,
+  });
+  const provider = String(options.provider || credential?.metadata?.provider || "codex");
+  const api = new ApiClient({ baseUrl: baseUrl(options), userAgent: USER_AGENT });
+  const index = await api.request("", { auth: false });
+  const liveContract = dictLike(index?.coding_agent_collaboration);
+  const serverVersion = String(liveContract.version || "").trim() || null;
+  const guidance = await inspectCollaborationGuidance(provider, projectRoot, serverVersion);
+  const bindingId = String(credential?.metadata?.binding_id || "").trim();
+  const runnerState = await readAgentRunnerState();
+  const listener = bindingId ? dictLike(runnerState?.listeners?.[bindingId]) : {};
+  const listenerStatus = processIsRunning(Number(listener.pid)) ? "listening" : "offline";
+  let status = "ready";
+  if (!credential) status = "needs_connection";
+  else if (!serverVersion) status = "contract_unavailable";
+  else if (guidance.status === "missing") status = "needs_skill";
+  else if (guidance.status === "stale") status = "stale_skill";
+  const nextActions = [];
+  if (!credential) nextActions.push(`corvio agents connect --provider ${provider} --project .`);
+  if (guidance.install_command) nextActions.push(guidance.install_command);
+  if (!serverVersion) nextActions.push("corvio update check --json");
+  writeResult({
+    status,
+    foreground_collaboration_ready: status === "ready",
+    contract_version: serverVersion,
+    server_contract_version: serverVersion,
+    project_agent: credential
+      ? {
+          connected: true,
+          id: credential.metadata?.agent_id || null,
+          provider,
+          binding_id: bindingId || null,
+        }
+      : { connected: false, id: null, provider, binding_id: null },
+    host_guidance: guidance,
+    listener_status: listenerStatus,
+    listener_note: "The listener receives inbound @Agent work; it does not activate foreground Coding-Agent collaboration.",
+    synchronization: {
+      mode: "host_guided_foreground",
+      automatic_transcript_capture: false,
+      reason: "The host selects decision-relevant context and valuable results; Corvio never records arbitrary chats or local files in the background.",
+      work_loop: liveContract.work_loop || ["ground", "work", "checkpoint", "materialize", "verify", "return"],
+    },
+    next_actions: nextActions,
+  }, { json: options.json });
+}
+
 async function workspaces(options, action, id) {
   const credential = await readWorkspaceCredential();
   if (!credential) {
@@ -1224,6 +1365,22 @@ async function agents(options, action, id) {
     const listener = options["no-listen"]
       ? { status: "offline", pid: null, reused: false, log: null }
       : await ensureAgentListener({ options, provider, agentId: agent.id, binding });
+    let collaborationVersion = null;
+    try {
+      const collaborationIndex = await api.request("", { auth: false });
+      collaborationVersion = String(
+        dictLike(collaborationIndex?.coding_agent_collaboration).version || "",
+      ).trim() || null;
+    } catch {
+      // The Agent binding and provider readiness are already durable. Keep this
+      // later collaboration check explicit instead of turning a settled connect
+      // into an ambiguous failure.
+    }
+    const hostGuidance = await inspectCollaborationGuidance(
+      provider,
+      binding.project_root,
+      collaborationVersion,
+    );
     result = {
       connected: true,
       idempotent: Boolean(result.idempotent),
@@ -1258,8 +1415,20 @@ async function agents(options, action, id) {
         reused: listener.reused,
         log: listener.log,
       },
+      foreground_collaboration: {
+        status: hostGuidance.status === "ready"
+          ? "ready"
+          : hostGuidance.status === "contract_unavailable"
+            ? "contract_unavailable"
+            : "needs_skill",
+        ready: hostGuidance.status === "ready",
+        host_guidance: hostGuidance,
+        note: "The inbound listener and foreground collaboration are separate readiness facts.",
+      },
       settings_url: result.settings_url,
-      next_command: `corvio agent run --provider ${provider} --agent ${agent.id}`,
+      next_command: hostGuidance.status === "ready"
+        ? "corvio collaboration status --json --no-input"
+        : hostGuidance.install_command || "corvio collaboration status --json --no-input",
     };
   } else if (action === "create") {
     result = await api.request("/agents", {
@@ -2196,6 +2365,97 @@ async function agentCommand(options, action, id) {
       method: "POST",
       body: { status: option(options, "status", { required: true }), entry_point: "external_agent_cli_status" },
     });
+  } else if (action === "closeout") {
+    const documentId = option(options, "document-id", { required: true });
+    const threadId = String(options["thread-id"] || "").trim() || null;
+    const bodyText = option(options, "body", { required: true });
+    const status = String(options.status || "open").trim().toLowerCase();
+    if (!["open", "resolved"].includes(status)) {
+      throw new CliError("--status must be open or resolved.", { code: "comment_status_invalid" });
+    }
+    const before = await api.request(`/documents/${resourcePath(documentId)}/comments`);
+    if (threadId && !Array.isArray(before?.threads)) {
+      throw new CliError("The current comment readback is invalid.", { code: "comment_readback_invalid" });
+    }
+    if (threadId && !before.threads.some((thread) => String(thread.id) === threadId)) {
+      throw new CliError("The originating comment thread was not found on this document.", {
+        code: "comment_thread_not_found",
+      });
+    }
+    const stableKey = idempotencyKey(options);
+    const mentionTargets = await resolveAgentMentionTargets(api, documentId, bodyText);
+    const comment = threadId
+      ? await api.request(`/documents/${resourcePath(documentId)}/comments/${resourcePath(threadId)}/replies`, {
+          method: "POST",
+          headers: { "idempotency-key": stableKey },
+          body: {
+            body: bodyText,
+            mention_targets: mentionTargets,
+            entry_point: "external_agent_cli_closeout",
+            start_new_chain: false,
+          },
+        })
+      : await api.request(`/documents/${resourcePath(documentId)}/comments`, {
+          method: "POST",
+          headers: { "idempotency-key": stableKey },
+          body: {
+            body: bodyText,
+            mention_targets: mentionTargets,
+            selection: { target_scope: "document" },
+            entry_point: "external_agent_cli_closeout",
+            start_new_chain: false,
+          },
+        });
+    const closeoutThreadId = String(comment?.id || threadId || "");
+    try {
+      if (status === "resolved" && String(comment?.status || "") !== "resolved") {
+        await api.request(`/documents/${resourcePath(documentId)}/comments/${resourcePath(closeoutThreadId)}/status`, {
+          method: "POST",
+          body: { status: "resolved", entry_point: "external_agent_cli_closeout" },
+        });
+      }
+    } catch {
+      throw new CliError(
+        "The result comment was committed, but the requested closeout status failed. Keep the thread open and retry the status update after readback.",
+        {
+          code: "comment_closeout_partial",
+          exitCode: EXIT.REMOTE,
+          details: { document_id: documentId, thread_id: closeoutThreadId, comment },
+        },
+      );
+    }
+    const [document, comments] = await Promise.all([
+      api.request(`/documents/${resourcePath(documentId)}`),
+      api.request(`/documents/${resourcePath(documentId)}/comments`),
+    ]);
+    const thread = Array.isArray(comments?.threads)
+      ? comments.threads.find((item) => String(item.id) === closeoutThreadId) || null
+      : null;
+    if (!thread) {
+      throw new CliError(
+        "The result comment was committed, but its current thread could not be read back.",
+        {
+          code: "comment_closeout_readback_failed",
+          exitCode: EXIT.REMOTE,
+          details: { document_id: documentId, thread_id: closeoutThreadId, comment },
+        },
+      );
+    }
+    result = {
+      document: {
+        id: document?.id || documentId,
+        node_id: document?.node_id || null,
+        title: document?.title || null,
+        doc_type: document?.doc_type || null,
+        content_revision: document?.content_revision ?? null,
+        url: document?.url || null,
+      },
+      thread,
+      completed: status === "resolved" && thread?.status === "resolved",
+      remaining_boundary: status === "resolved" && thread?.status === "resolved"
+        ? null
+        : "The originating thread remains open for incomplete or unverified work.",
+    };
   } else {
     throw new CliError("Unknown agent runtime action.");
   }
@@ -3037,6 +3297,7 @@ async function main({ options, positionals }) {
     return workspaces(options, action || "list", id);
   }
   if (command === "capabilities") return capabilities(options);
+  if (command === "collaboration") return collaborationStatus(options);
   if (command === "ask") return ask(options, [action, id, ...rest].filter(Boolean));
   if (command === "agents") return agents(options, action || "list", id);
   if (command === "agent") return agentCommand(options, action || "claim", id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@corvio/cli",
-  "version": "0.1.0-beta.14",
+  "version": "0.1.0-beta.15",
   "description": "Official Corvio Workspace CLI for questions, knowledge search, documents, and Agent workflows.",
   "type": "module",
   "bin": {