chainlesschain 0.162.163 → 0.162.164

package/src/commands/doctor.js

@@ -1,12 +1,80 @@
 import chalk from "chalk";
+import { existsSync, readdirSync, writeFileSync } from "node:fs";
+import { join as pathJoin } from "node:path";
 import logger from "../lib/logger.js";
-import { collectDoctorReport } from "../runtime/diagnostics.js";
+import {
+  collectDoctorReport,
+  collectWorktrees,
+  buildDoctorDiagnosticInput,
+} from "../runtime/diagnostics.js";
+import { getHomeDir } from "../lib/paths.js";
+import { exportDiagnosticBundle } from "../lib/diagnostic-bundle.js";
 import {
   collectCheckupSections,
   runCheckupFixes,
   unsafeFixCommands,
 } from "../lib/doctor-checkup.js";
 
+/** Best-effort top-level `*.lock` files under the config home dir. */
+function collectLockfiles() {
+  try {
+    const home = getHomeDir();
+    if (!home || !existsSync(home)) return [];
+    return readdirSync(home)
+      .filter((f) => f.endsWith(".lock"))
+      .map((f) => pathJoin(home, f));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Assemble a de-identified diagnostic bundle from the live doctor report and
+ * run the mandatory secret-scan gate. On a clean gate, writes JSON to `outPath`
+ * (or prints it) and returns `{ ok: true }`. If the gate blocks (residual
+ * secret — defense-in-depth, should not happen post-redaction), prints the leak
+ * locations and returns `{ ok: false }` without exporting.
+ */
+export async function runExportBundle(report, outPath) {
+  const input = buildDoctorDiagnosticInput(report, {
+    env: process.env,
+    worktrees: collectWorktrees(),
+    lockfiles: collectLockfiles(),
+  });
+  const { ok, bundle, findings } = exportDiagnosticBundle(input);
+
+  if (!ok) {
+    logger.log(
+      chalk.red(
+        "\n  ✖ Diagnostic bundle blocked by secret scan (not exported).",
+      ),
+    );
+    for (const f of findings) {
+      logger.log(chalk.gray(`    ${f.path || "?"}: ${f.category || "secret"}`));
+    }
+    process.exitCode = 1;
+    return { ok: false };
+  }
+
+  const json = JSON.stringify(bundle, null, 2);
+  if (outPath) {
+    writeFileSync(outPath, json, "utf-8");
+    logger.log(
+      chalk.green(
+        `\n  ✔ De-identified diagnostic bundle written to ${outPath}`,
+      ),
+    );
+    logger.log(
+      chalk.gray(
+        "    Excludes source, API keys, cookies, env values and terminal output.",
+      ),
+    );
+  } else {
+    console.log(json);
+  }
+  return { ok: true };
+}
+
 const LEVEL_ICON = {
   ok: () => chalk.green("✔"),
   warn: () => chalk.yellow("⚠"),
@@ -21,8 +89,24 @@ export function registerDoctorCommand(program) {
     .description("Diagnose your ChainlessChain environment (alias: checkup)")
     .option("--json", "Output as machine-readable JSON")
     .option("--fix", "Apply safe fixes (stale job files, git worktree prune)")
+    .option(
+      "--export-bundle [path]",
+      "Export a de-identified diagnostic bundle (secret-scanned; excludes source/keys/env values). Writes to <path>, or stdout when no path is given.",
+    )
     .action(async (options) => {
       const report = await collectDoctorReport();
+
+      // One-click de-identified diagnostic bundle. Bypasses the human-readable
+      // render entirely: it is a support artifact, not a terminal read-out.
+      if (options.exportBundle !== undefined) {
+        const outPath =
+          typeof options.exportBundle === "string"
+            ? options.exportBundle
+            : null;
+        await runExportBundle(report, outPath);
+        return;
+      }
+
       const sections = await collectCheckupSections({ cwd: process.cwd() });
       const fixResults = options.fix ? await runCheckupFixes(sections) : null;
 

package/src/commands/plugin.js

@@ -64,8 +64,12 @@ async function resolvePluginCapabilityNotice(name, scope, cwd) {
   }
 }
 
-/** Print the capability notice (text mode) after an install/upgrade. */
-function printPluginCapabilityNotice(name, notice) {
+/**
+ * Print the capability notice (text mode) after an install/upgrade. Pass
+ * `{ hint: false }` to omit the trailing `cc plugin consent … --grant` pointer
+ * when consent is being granted inline (explicit flag or interactive prompt).
+ */
+function printPluginCapabilityNotice(name, notice, { hint = true } = {}) {
   if (!notice) return;
   logger.log(chalk.bold("\nCapabilities (declared):"));
   for (const l of notice.declared) logger.log(`  ${chalk.magenta(l)}`);
@@ -78,9 +82,81 @@ function printPluginCapabilityNotice(name, notice) {
   );
   if (notice.added.length)
     logger.log(chalk.yellow(`    new: ${notice.added.join(", ")}`));
-  logger.log(
-    chalk.dim(`    run \`cc plugin consent ${name} --grant\` to allow them`),
-  );
+  if (hint)
+    logger.log(
+      chalk.dim(`    run \`cc plugin consent ${name} --grant\` to allow them`),
+    );
+}
+
+/**
+ * Record consent for a freshly installed/upgraded plugin's currently-declared
+ * capabilities (re-discovers to get the raw declared set + version). Best-effort
+ * — returns false rather than throwing so it can never break an install.
+ */
+async function grantInstalledPluginCapabilities(name, scope, cwd) {
+  try {
+    const { discoverPlugins } = await import("../lib/plugin-runtime/scopes.js");
+    const consent = await import("../lib/plugin-runtime/capability-consent.js");
+    const installed = discoverPlugins({ cwd, skipPolicy: true }).find(
+      (p) => p.name === name && p.scope === scope,
+    );
+    if (!installed) return false;
+    const declared = installed.manifest?.capabilities;
+    if (!declared || consent.capabilitiesAreEmpty(declared)) return false;
+    consent.consentPluginCapabilities(name, {
+      scope,
+      version: installed.version,
+      capabilities: declared,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Handle the capability-consent gate after a text-mode install/upgrade: print
+ * the notice and, when consent is required, either auto-grant (explicit
+ * `--grant-capabilities`) or block interactively (TTY) to grant it right away
+ * instead of forcing a separate `cc plugin consent --grant` step. Returns true
+ * if consent was recorded during this call.
+ */
+async function applyCapabilityConsentGate(name, scope, notice, cwd, opts = {}) {
+  const consent = await import("../lib/plugin-runtime/capability-consent.js");
+  const action = consent.resolveConsentAction(notice, {
+    grant: opts.grant === true,
+    interactive: opts.interactive === true,
+  });
+  if (action === "advisory") {
+    printPluginCapabilityNotice(name, notice);
+    return false;
+  }
+  // Show the ⚠ notice + new-capability diff before deciding; suppress the
+  // "run cc plugin consent" pointer since we grant inline here.
+  printPluginCapabilityNotice(name, notice, { hint: false });
+  if (action === "prompt") {
+    let ok = false;
+    try {
+      const { confirm } = await import("@inquirer/prompts");
+      ok = await confirm({
+        message: `Grant these capabilities to ${name} now?`,
+        default: false,
+      });
+    } catch {
+      ok = false; // Ctrl-C / non-interactive → treat as decline (fail closed)
+    }
+    if (!ok) {
+      logger.log(
+        chalk.dim(
+          "    capabilities not granted — components needing them stay disabled",
+        ),
+      );
+      return false;
+    }
+  }
+  const granted = await grantInstalledPluginCapabilities(name, scope, cwd);
+  if (granted) logger.success(`  ✔ capability consent granted for ${name}`);
+  return granted;
 }
 
 export function registerPluginCommand(program) {
@@ -738,6 +814,10 @@ export function registerPluginCommand(program) {
       "--allow-insecure-registry",
       "Allow a plain-HTTP registry URL (MITM risk — trusted networks only)",
     )
+    .option(
+      "--grant-capabilities",
+      "Grant the plugin's declared capabilities at install time (no separate consent step)",
+    )
     .option("--json", "Output as JSON")
     .action(async (source, options) => {
       const { installFromSource } =
@@ -806,8 +886,21 @@ export function registerPluginCommand(program) {
           process.cwd(),
         );
         if (options.json) {
+          // Non-interactive JSON path: honor an explicit --grant-capabilities so
+          // scripted installs can consent atomically; never prompt.
+          let capabilitiesGranted = false;
+          if (options.grantCapabilities && capNotice && !capNotice.consented)
+            capabilitiesGranted = await grantInstalledPluginCapabilities(
+              res.name,
+              res.scope,
+              process.cwd(),
+            );
           console.log(
-            JSON.stringify({ ...res, capabilities: capNotice }, null, 2),
+            JSON.stringify(
+              { ...res, capabilities: capNotice, capabilitiesGranted },
+              null,
+              2,
+            ),
           );
         } else {
           logger.success(
@@ -817,7 +910,16 @@ export function registerPluginCommand(program) {
           logger.log(chalk.gray(`  → ${res.dir}`));
           for (const w of res.warnings || [])
             logger.log(chalk.yellow(`  ⚠ ${w}`));
-          printPluginCapabilityNotice(res.name, capNotice);
+          await applyCapabilityConsentGate(
+            res.name,
+            res.scope,
+            capNotice,
+            process.cwd(),
+            {
+              grant: options.grantCapabilities === true,
+              interactive: Boolean(process.stdin.isTTY),
+            },
+          );
         }
       } catch (err) {
         logger.error(`Install failed: ${err.message}`);
@@ -1132,6 +1234,110 @@ export function registerPluginCommand(program) {
       }
     });
 
+  // plugin options — view a plugin's resolved typed options, or set values at a
+  // scope. The security-critical rule: a SENSITIVE option can never be set from
+  // PROJECT scope (a checked-in file must not inject secrets) — such values are
+  // dropped + warned; use `--scope user`.
+  plugin
+    .command("options <name>")
+    .description(
+      "View or set a plugin's typed options (--set key=value, --scope user|project)",
+    )
+    .option("--scope <scope>", "Scope for --set (user|project)", "user")
+    .option(
+      "--set <pair>",
+      "Set an option value (key=value); repeatable",
+      (v, acc) => {
+        acc.push(v);
+        return acc;
+      },
+      [],
+    )
+    .option("--json", "Output as JSON")
+    .action(async (name, options) => {
+      const { discoverPlugins } =
+        await import("../lib/plugin-runtime/scopes.js");
+      const optsMod = await import("../lib/plugin-runtime/plugin-options.js");
+
+      let installed = null;
+      try {
+        installed = discoverPlugins({
+          cwd: process.cwd(),
+          skipPolicy: true,
+        }).find((p) => p.name === name);
+      } catch {
+        /* discovery best-effort */
+      }
+      if (!installed) {
+        logger.error(`${name} is not installed`);
+        process.exitCode = 1;
+        return;
+      }
+      const schema = installed.manifest?.optionsSchema || {};
+
+      // --set: persist values at the requested scope (then fall through to show).
+      if (options.set && options.set.length) {
+        const scope = options.scope === "project" ? "project" : "user";
+        const current = optsMod.loadPluginOptionValues(name, scope, {
+          cwd: process.cwd(),
+        });
+        for (const pair of options.set) {
+          const eq = pair.indexOf("=");
+          if (eq <= 0) {
+            logger.error(`Invalid --set "${pair}" (expected key=value)`);
+            process.exitCode = 1;
+            return;
+          }
+          current[pair.slice(0, eq)] = pair.slice(eq + 1);
+        }
+        optsMod.setPluginOptionValues(name, current, scope, {
+          cwd: process.cwd(),
+        });
+        logger.success(`Set option(s) for ${name} at ${scope} scope`);
+      }
+
+      const resolved = optsMod.getResolvedPluginOptions(name, schema, {
+        cwd: process.cwd(),
+      });
+      if (options.json) {
+        console.log(
+          JSON.stringify(
+            {
+              name,
+              scope: installed.scope,
+              options: resolved.redacted,
+              sources: resolved.sources,
+              warnings: resolved.warnings,
+              droppedFromProject: resolved.droppedFromProject,
+            },
+            null,
+            2,
+          ),
+        );
+        return;
+      }
+      logger.log(chalk.bold(`Options: ${chalk.cyan(name)}`));
+      const keys = Object.keys(resolved.redacted);
+      if (keys.length === 0) logger.log(chalk.gray("  (no options)"));
+      for (const k of keys) {
+        logger.log(
+          `  ${chalk.cyan(k)} = ${resolved.redacted[k]} ${chalk.gray(
+            `[${resolved.sources[k] || "default"}]`,
+          )}`,
+        );
+      }
+      if (resolved.droppedFromProject.length) {
+        logger.log(
+          chalk.yellow(
+            `  ⚠ dropped from project config (sensitive/user-only): ${resolved.droppedFromProject.join(
+              ", ",
+            )} — set with --scope user`,
+          ),
+        );
+      }
+      for (const w of resolved.warnings) logger.log(chalk.gray(`  ${w}`));
+    });
+
   // plugin monitors — list (and optionally run) trusted plugins' background
   // monitors. `--run --seconds N` actually starts the supervisor for N seconds,
   // prints captured output, then reaps everything (verifies no leaked process).
@@ -1218,6 +1424,10 @@ export function registerPluginCommand(program) {
     )
     .option("--scope <scope>", `Scope to update in (${SCOPES})`, "user")
     .option("--force", "Reinstall even if the version is unchanged")
+    .option(
+      "--grant-capabilities",
+      "Grant any newly declared capabilities during the upgrade (no separate consent step)",
+    )
     .action(async (source, options) => {
       const { updatePlugin } = await import("../lib/plugin-runtime/install.js");
       try {
@@ -1241,14 +1451,21 @@ export function registerPluginCommand(program) {
         }
         // Surface the (possibly widened) capability set + re-consent hint. An
         // upgrade that adds a capability shows a `⚠ capability consent required`
-        // notice diffed against the prior consent.
-        printPluginCapabilityNotice(
+        // notice diffed against the prior consent, then either auto-grants
+        // (--grant-capabilities) or blocks interactively to re-consent now.
+        await applyCapabilityConsentGate(
           res.name,
+          options.scope,
           await resolvePluginCapabilityNotice(
             res.name,
             options.scope,
             process.cwd(),
           ),
+          process.cwd(),
+          {
+            grant: options.grantCapabilities === true,
+            interactive: Boolean(process.stdin.isTTY),
+          },
         );
       } catch (err) {
         logger.error(`Upgrade failed: ${err.message}`);

package/src/commands/review.js

@@ -848,7 +848,23 @@ export async function runMultiFinderReview(ctx = {}, deps = {}) {
     verifiedCount = Object.values(verdicts).filter((v) => v.verified).length;
   }
 
-  const report = buildReviewReport(all, { verdicts });
+  // P1-1: read each referenced file's current content so every finding's output
+  // carries a re-anchorable comment anchor (file + base hash + line + context),
+  // not just a bare line number — an IDE diff review can then relocate or stale
+  // the comment after the agent's fix instead of reusing a dead coordinate.
+  // Best-effort: an unreadable path is simply skipped (no anchor for it).
+  const reviewCwd = ctx.baseOptions?.cwd || process.cwd();
+  const readFile = deps.readFileSync || fs.readFileSync;
+  const fileContents = new Map();
+  for (const p of new Set(all.map((f) => f && f.path).filter(Boolean))) {
+    try {
+      fileContents.set(p, readFile(path.resolve(reviewCwd, p), "utf-8"));
+    } catch {
+      /* file gone / binary / outside tree — no anchor, never fail the review */
+    }
+  }
+
+  const report = buildReviewReport(all, { verdicts, fileContents });
   const meta = {
     byDimension,
     ...(ctx.verify ? { verified: verifiedCount } : {}),

package/src/commands/session.js

@@ -9,6 +9,7 @@ import path from "path";
 import chalk from "chalk";
 import { logger } from "../lib/logger.js";
 import { parseJsonOption } from "../lib/parse-json-option.js";
+import { scanSecrets, redactSecrets } from "../lib/secret-scan.js";
 import { bootstrap, shutdown } from "../runtime/bootstrap.js";
 import {
   listSessions,
@@ -75,6 +76,97 @@ function _sessionEpoch(ts) {
   return Number.isFinite(n) ? n : 0;
 }
 
+/**
+ * Render a PR's automation status (P1-4 "PR/CI Monitor + 受控合并") from a
+ * gathered signals object — PURE, so it is testable without gh / the network.
+ * `enabled` mirrors the "auto-merge is OFF by default" rule: only an explicit
+ * opt-in even considers a merge. Everything else defers to the fail-closed
+ * pr-automation-policy decision engine.
+ *
+ * @param {object} signals  {branch, prNumber, hasOpenPr, headCommitSha,
+ *   branchProtectionSatisfied, reviewApproved, pendingApprovals,
+ *   requiredChecks, checks}
+ * @param {{enabled?:boolean}} [opts]
+ * @returns {{statusBar:string, autoMerge:{allow:boolean,reason:string,unmet:string[]}, lines:string[]}}
+ */
+export async function renderPrStatus(signals = {}, opts = {}) {
+  const { autoMergeDecision, describePrStatusBar } =
+    await import("../lib/pr-automation-policy.js");
+  const autoMerge = autoMergeDecision({
+    enabled: opts.enabled === true,
+    hasOpenPr: signals.hasOpenPr,
+    branchProtectionSatisfied: signals.branchProtectionSatisfied,
+    reviewApproved: signals.reviewApproved,
+    pendingApprovals: signals.pendingApprovals,
+    requiredChecks: signals.requiredChecks,
+    checks: signals.checks,
+  });
+  const statusBar = describePrStatusBar({
+    branch: signals.branch,
+    prNumber: signals.prNumber,
+    checks: signals.checks,
+    reviewApproved: signals.reviewApproved,
+    mergeable: autoMerge.allow,
+  });
+  const lines = [statusBar];
+  if (autoMerge.allow) {
+    lines.push("auto-merge: ✓ eligible");
+  } else {
+    lines.push(`auto-merge: ✗ blocked (${autoMerge.unmet.join(", ")})`);
+  }
+  return { statusBar, autoMerge, lines };
+}
+
+/**
+ * Best-effort map of `gh pr view --json …` output to the pr-automation signals.
+ * PURE (json → json); the command supplies the gh JSON (or a --checks-file). A
+ * missing field stays undefined so the fail-closed policy denies rather than
+ * assuming.
+ */
+export function mapGhPrToSignals(gh = {}) {
+  const rollup = Array.isArray(gh.statusCheckRollup)
+    ? gh.statusCheckRollup
+    : [];
+  return {
+    branch: gh.headRefName || undefined,
+    prNumber: gh.number,
+    hasOpenPr: String(gh.state || "").toUpperCase() === "OPEN",
+    headCommitSha: gh.headRefOid || undefined,
+    reviewApproved: gh.reviewDecision === "APPROVED",
+    // gh doesn't expose branch-protection satisfaction or pending in-app
+    // approvals here; leave them undefined → fail-closed unless a --checks-file
+    // asserts them.
+    checks: rollup.map((c) => ({
+      name: c.name || c.context,
+      // check runs use `conclusion`; legacy statuses use `state`.
+      state: c.conclusion || c.state || c.status,
+    })),
+  };
+}
+
+/**
+ * Best-effort live fetch of a PR's signals via `gh pr view --json`. Returns the
+ * mapped signals, or throws (caller degrades to a "pass --checks-file" hint).
+ * 8s timeout, stderr suppressed — a missing / unauthenticated gh just fails.
+ */
+async function fetchPrSignalsViaGh(target) {
+  const { execFileSync } = await import("node:child_process");
+  const args = [
+    "pr",
+    "view",
+    String(target.number),
+    "--json",
+    "number,state,headRefName,headRefOid,reviewDecision,statusCheckRollup",
+  ];
+  if (target.repo) args.push("--repo", String(target.repo));
+  const out = execFileSync("gh", args, {
+    encoding: "utf-8",
+    timeout: 8000,
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  return mapGhPrToSignals(JSON.parse(out));
+}
+
 export function rankSessions(sessions, limit) {
   // Dedup by id, preferring the JSONL copy when a session exists in both stores
   // (the original "JSONL takes precedence" intent, previously achieved only as
@@ -254,6 +346,87 @@ export function registerSessionCommand(program) {
       }
     });
 
+  // session pr-status — PR/CI monitor + controlled auto-merge decision (P1-4)
+  // for a session's linked PR. Offline-testable via --checks-file; otherwise a
+  // best-effort `gh pr view` fetch for the session's newest linked PR.
+  session
+    .command("pr-status")
+    .description(
+      "PR/CI monitor + controlled auto-merge decision for a session's linked PR",
+    )
+    .argument("[id]", "Session id (default: most recent)")
+    .option("--pr <number>", "Which linked PR to assess (default: newest)")
+    .option(
+      "--checks-file <path>",
+      "JSON file of PR signals {branch,prNumber,hasOpenPr,branchProtectionSatisfied,reviewApproved,pendingApprovals,requiredChecks,checks} — bypasses gh",
+    )
+    .option("--enable", "Consider auto-merge eligibility (default: off)")
+    .option("--json", "Output as machine-readable JSON")
+    .action(async (id, options) => {
+      try {
+        let signals = null;
+        let source = "";
+        if (options.checksFile) {
+          // Offline / explicit path: the caller supplies the PR signals.
+          signals = JSON.parse(fs.readFileSync(options.checksFile, "utf-8"));
+          source = options.checksFile;
+        } else {
+          // Live path: resolve the session's linked PR and fetch via gh.
+          const { getPrLinks } = await import("../lib/pr-link-ledger.js");
+          const { getLastSessionId } =
+            await import("../harness/jsonl-session-store.js");
+          const sid = !id || id === "last" ? getLastSessionId() : id;
+          const links = sid ? getPrLinks(sid) : [];
+          if (links.length === 0) {
+            logger.error(
+              "No linked PRs for this session — pass --checks-file to assess a PR directly.",
+            );
+            process.exit(1);
+          }
+          let target;
+          if (options.pr) {
+            target = links.find((l) => String(l.number) === String(options.pr));
+            if (!target) {
+              logger.error(`Session has no linked PR #${options.pr}.`);
+              process.exit(1);
+            }
+          } else {
+            // Newest by updatedAt (epoch-normalized; unknowns sort last).
+            target = links
+              .slice()
+              .sort(
+                (a, b) =>
+                  (Date.parse(b.updatedAt) || 0) -
+                  (Date.parse(a.updatedAt) || 0),
+              )[0];
+          }
+          signals = await fetchPrSignalsViaGh(target).catch(() => null);
+          if (!signals) {
+            logger.error(
+              `Could not fetch PR #${target.number} via gh — authenticate gh or pass --checks-file.`,
+            );
+            process.exit(1);
+          }
+          source = `gh:${target.repo || "?"}#${target.number}`;
+        }
+
+        const result = await renderPrStatus(signals, {
+          enabled: options.enable === true,
+        });
+        if (options.json) {
+          console.log(JSON.stringify({ source, ...result }, null, 2));
+        } else {
+          logger.log(
+            chalk.bold("PR automation status") + chalk.gray(`  (${source})`),
+          );
+          for (const line of result.lines) logger.log(`  ${line}`);
+        }
+      } catch (err) {
+        logger.error(`Failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
   // session resume
   session
     .command("resume")
@@ -368,6 +541,10 @@ export function registerSessionCommand(program) {
       "Session ID (or prefix; `last` = most recent agent session)",
     )
     .option("-o, --output <file>", "Output file path")
+    .option(
+      "--no-redact",
+      "Do NOT redact detected secrets from the exported transcript (default: redact)",
+    )
     .action(async (id, options) => {
       try {
         let markdown = null;
@@ -406,6 +583,20 @@ export function registerSessionCommand(program) {
           process.exit(1);
         }
 
+        // §8.1 export gate: a transcript can carry provider tokens, JWTs,
+        // connection strings or cookies (in tool commands / results). Redact by
+        // default — an export leaves the machine and must fail toward "no leak".
+        // `--no-redact` keeps raw values for the user's own trusted backup.
+        if (options.redact !== false) {
+          const findings = scanSecrets(markdown);
+          if (findings.length > 0) {
+            markdown = redactSecrets(markdown);
+            logger.warn(
+              `Redacted ${findings.length} secret${findings.length === 1 ? "" : "s"} from the export (use --no-redact to keep raw values).`,
+            );
+          }
+        }
+
         if (options.output) {
           fs.writeFileSync(options.output, markdown, "utf8");
           logger.success(`Exported to ${chalk.cyan(options.output)}`);

package/src/commands/team.js

@@ -215,6 +215,14 @@ export function registerTeamCommand(program, { logger } = {}) {
       "--merge",
       "With --worktree: merge each clean branch back to base (conflicts reported, not forced)",
     )
+    .option(
+      "--sparse-paths <paths>",
+      "With --worktree: comma-separated packages to sparse-checkout (only these are materialized)",
+    )
+    .option(
+      "--symlink-dirs <dirs>",
+      "With --worktree: comma-separated approved dependency dirs to symlink from the main checkout (e.g. node_modules)",
+    )
     .option("--max-tasks <n>", "Budget: total task executions across the team")
     .option("--max-tokens <n>", "Budget: total LLM tokens across the team")
     .option(
@@ -348,7 +356,17 @@ export function registerTeamCommand(program, { logger } = {}) {
       let runTask;
       let coord = null;
       if (options.worktree) {
-        coord = new TeamWorktreeCoordinator(process.cwd());
+        const splitList = (v) =>
+          v
+            ? String(v)
+                .split(",")
+                .map((s) => s.trim())
+                .filter(Boolean)
+            : null;
+        coord = new TeamWorktreeCoordinator(process.cwd(), {
+          sparsePaths: splitList(options.sparsePaths),
+          symlinkDirectories: splitList(options.symlinkDirs),
+        });
         if (!coord.isGitRepo()) {
           (log.error || console.error)(
             "--worktree requires a git repository (run inside one)",