@monster-orange/den 0.3.0 → 0.4.1

package/src/ui/cli/env-probe.ts

@@ -0,0 +1,266 @@
+/**
+ * `<cli> doctor --probe` (AG spec §5a-env): check, through the real session
+ * host and backend, what environment a session actually gets. Opt-in: plain
+ * `doctor` never spawns anything.
+ *
+ * For a plain session (as `sessions start` builds it, no --keep-env) and
+ * for each available runtime's agent env (as `agents start` builds it, the
+ * runtime's launch env included, but running the probe instead of the
+ * runtime's CLI), it starts a short session running a tiny node script that
+ * prints each key name and one flag: whether the name or value is
+ * credential-shaped (secret-env.ts, with the redactor's patterns). Values
+ * never leave the probe process.
+ *
+ * A finding is any runtime's scrubEnv name, or any credential-shaped
+ * variable, in either env.
+ */
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import {
+  agentSessionEnv,
+  allScrubEnv,
+  getRuntime,
+  LaunchError,
+  runtimeIds,
+  type LaunchInput,
+  type Runtime,
+} from "../../shared/agents/runtimes.js";
+import { credentialPatternData } from "../../shared/secret-env.js";
+import type { HostClient } from "../../shared/sessions/client.js";
+import { matchesScrub } from "../../shared/sessions/env.js";
+import { sessionName } from "../../shared/sessions/names.js";
+import type { PtyLoad } from "../../shared/sessions/pty.js";
+
+const MARK = "DENPROBE";
+const PROBE_ID = "env-probe";
+/** How long one probe session gets to print and exit. */
+const PROBE_TIMEOUT_MS = 10_000;
+
+/** The probe: key names and a 0/1 flag per key, then an end mark. No values. */
+export function probeScript(): string {
+  const p = JSON.stringify(credentialPatternData());
+  return [
+    `const P = ${p};`,
+    `const re = (l) => l.map((r) => new RegExp(r.source, r.flags));`,
+    `const N = re(P.name), V = re(P.value);`,
+    `for (const k of Object.keys(process.env).sort()) {`,
+    `  const v = process.env[k] || "";`,
+    `  const c = N.some((r) => r.test(k)) || (v !== "" && V.some((r) => r.test(v)));`,
+    `  process.stdout.write("${MARK} " + k + " " + (c ? 1 : 0) + "\\n");`,
+    `}`,
+    `process.stdout.write("${MARK}-END\\n");`,
+  ].join("\n");
+}
+
+export interface ProbeKey {
+  name: string;
+  credentialShaped: boolean;
+}
+
+/** The probe's report from its output; null when it did not finish. */
+export function parseProbe(output: string): ProbeKey[] | null {
+  const keys: ProbeKey[] = [];
+  let ended = false;
+  for (const raw of output.split(/\r?\n/)) {
+    const line = raw.replace(/\r/g, "").trim();
+    if (line === `${MARK}-END`) ended = true;
+    const m = new RegExp(`^${MARK} ([A-Za-z_][A-Za-z0-9_]*) ([01])$`).exec(
+      line,
+    );
+    if (m) keys.push({ name: m[1], credentialShaped: m[2] === "1" });
+  }
+  return ended ? keys : null;
+}
+
+export interface ProbeFinding {
+  key: string;
+  why: string;
+}
+
+export interface ProbeResult {
+  /** "plain session", or "agent (<runtime>)". */
+  target: string;
+  /** False: not probed (the reason says why); never a failure. */
+  ran: boolean;
+  reason?: string;
+  keys?: number;
+  findings: ProbeFinding[];
+}
+
+export interface ProbeDeps {
+  dist: string;
+  cli: string;
+  env: NodeJS.ProcessEnv;
+  pty: () => PtyLoad;
+  connect: () => Promise<HostClient>;
+  /** A plain session's env, as `sessions start` builds it. */
+  plainEnv: (caller: NodeJS.ProcessEnv) => Record<string, string>;
+  /** An agent's env, as `agents start` builds it. */
+  agentEnv?: (
+    caller: NodeJS.ProcessEnv,
+    rt: Runtime,
+    launch: Record<string, string>,
+    agentId: string,
+  ) => Record<string, string>;
+  /** Runtimes to probe (default: every registered one that is available). */
+  runtimes?: () => Runtime[];
+}
+
+/** A launch input for the probe: nothing is written, nothing it names runs. */
+function probeInput(d: ProbeDeps, dir: string): LaunchInput {
+  return {
+    persona: {
+      id: PROBE_ID,
+      role: "",
+      prompt: "",
+      standing: false,
+      tools: [],
+      context: [],
+      argv: [PROBE_ID],
+      source: "doctor --probe",
+    },
+    workspace: { name: "doctor", dir },
+    agentId: PROBE_ID,
+    worktree: dir,
+    mcp: { name: d.cli, command: [d.cli], env: {}, scope: "doctor" },
+    // Never written: the probe uses only the launch's env.
+    filesDir: path.join(dir, PROBE_ID),
+    env: d.env,
+  };
+}
+
+function findings(keys: ProbeKey[]): ProbeFinding[] {
+  const scrub = allScrubEnv();
+  const out: ProbeFinding[] = [];
+  for (const k of keys) {
+    if (matchesScrub(k.name, scrub))
+      out.push({ key: k.name, why: "a runtime's scrubEnv name" });
+    else if (k.credentialShaped)
+      out.push({ key: k.name, why: "credential-shaped" });
+  }
+  return out;
+}
+
+/** Run the probe in one session with `env`; its report, or why not. */
+async function probeOnce(
+  d: ProbeDeps,
+  c: HostClient,
+  target: string,
+  slug: string,
+  env: Record<string, string>,
+  cwd: string,
+): Promise<ProbeResult> {
+  const info = await c.start({
+    name: sessionName(d.dist, "doctor", `${PROBE_ID}-${slug}`),
+    cwd,
+    argv: [process.execPath, "-e", probeScript()],
+    env,
+    cols: 200,
+    rows: 24,
+  });
+  try {
+    const deadline = Date.now() + PROBE_TIMEOUT_MS;
+    for (;;) {
+      const s = (await c.list()).find((x) => x.ref.id === info.ref.id);
+      if (!s || s.exited) break;
+      if (Date.now() > deadline) {
+        await c.kill(info.ref.id, "KILL").catch(() => undefined);
+        await new Promise((r) => setTimeout(r, 200));
+        break;
+      }
+      await new Promise((r) => setTimeout(r, 50));
+    }
+    const keys = parseProbe(
+      (await c.scrollback(info.ref.id, 1024 * 1024)).toString("utf-8"),
+    );
+    if (!keys)
+      return {
+        target,
+        ran: true,
+        findings: [{ key: "-", why: "the probe did not finish" }],
+      };
+    return { target, ran: true, keys: keys.length, findings: findings(keys) };
+  } finally {
+    await c.forget(info.ref.id).catch(() => undefined);
+  }
+}
+
+/** Probe a plain session and each available runtime's agent env. */
+export async function runEnvProbe(d: ProbeDeps): Promise<ProbeResult[]> {
+  const pty = d.pty();
+  if (!pty.available)
+    return [
+      {
+        target: "sessions",
+        ran: false,
+        reason: `den-pty is unavailable: ${pty.reason}`,
+        findings: [],
+      },
+    ];
+  const runtimes =
+    d.runtimes?.() ??
+    runtimeIds()
+      .map((id) => getRuntime(id))
+      .filter((rt): rt is Runtime => !!rt);
+  const agentEnv = d.agentEnv ?? agentSessionEnv;
+  // The probe writes nothing: its cwd is the temp dir, as it is.
+  const dir = fs.realpathSync(os.tmpdir());
+  const c = await d.connect();
+  try {
+    const out: ProbeResult[] = [
+      await probeOnce(d, c, "plain session", "plain", d.plainEnv(d.env), dir),
+    ];
+    for (const rt of runtimes) {
+      const target = `agent (${rt.id})`;
+      const det = rt.detect(d.env);
+      if (!det.available) {
+        out.push({
+          target,
+          ran: false,
+          reason: `${rt.id} is unavailable: ${det.why ?? "unknown"}`,
+          findings: [],
+        });
+        continue;
+      }
+      let launch: Record<string, string>;
+      try {
+        launch = rt.launch(probeInput(d, dir)).env;
+      } catch (e) {
+        if (!(e instanceof LaunchError)) throw e;
+        out.push({ target, ran: false, reason: e.message, findings: [] });
+        continue;
+      }
+      out.push(
+        await probeOnce(
+          d,
+          c,
+          target,
+          rt.id,
+          agentEnv(d.env, rt, launch, PROBE_ID),
+          dir,
+        ),
+      );
+    }
+    return out;
+  } finally {
+    c.close();
+  }
+}
+
+/** One line per result, one per finding; key names only. */
+export function formatProbe(results: ProbeResult[]): string[] {
+  const lines: string[] = [];
+  const width = Math.max(...results.map((r) => r.target.length));
+  for (const r of results) {
+    const t = r.target.padEnd(width);
+    if (!r.ran)
+      lines.push(`  ${t}  - not probed: ${r.reason ?? "unavailable"}`);
+    else if (!r.findings.length)
+      lines.push(`  ${t}  ✓ clean (${r.keys ?? 0} variables)`);
+    else
+      for (const f of r.findings)
+        lines.push(`  ${t}  ✗ ${f.key} reaches it (${f.why})`);
+  }
+  return lines;
+}

package/src/ui/cli/flag-parser.ts

@@ -77,10 +77,18 @@ const WORKSPACE_COMMANDS = new Set([
 
 /**
  * Commands that read `-w`/`--workspace` themselves, so it is left in their
- * args: `setup --plan -w a -w b` takes several, and `mcp --workspace <ws>`
- * scopes the MCP server (it never sets the CLI's workspace override).
+ * args: `setup --plan -w a -w b` takes several, `mcp --workspace <ws>`
+ * scopes the MCP server, and `sessions`/`agents` name a session's
+ * workspace. None of them sets the CLI's workspace override.
  */
-const OWN_WORKSPACE_FLAG_COMMANDS = new Set(["setup", "mcp"]);
+const OWN_WORKSPACE_FLAG_COMMANDS = new Set([
+  "setup",
+  "mcp",
+  // A session's workspace is part of its name (AG-3a); -w never sets the
+  // CLI's workspace override here.
+  "sessions",
+  "agents",
+]);
 
 /** Whether `-w <name>` on this command requires `<name>` to be active. */
 export function workspaceFlagRequiresActive(command: string): boolean {
@@ -162,6 +170,27 @@ function validateFlagScopes(parsed: ParsedCliArgs): void {
   }
 }
 
+/**
+ * Subcommands that print their own `--help`: the dispatcher's
+ * `<command> --help` must not answer for them (`web sessions --help` printed
+ * the general web help). web-command.ts's WEB_SUBCOMMANDS_WITH_HELP and
+ * mcp-connect.ts's MCP_CONNECT_SUBCOMMANDS are the same lists (a test
+ * checks).
+ */
+export const SUBCOMMAND_OWN_HELP: Readonly<Record<string, readonly string[]>> =
+  {
+    web: ["token", "login", "sessions", "logout"],
+    mcp: ["connect", "disconnect", "clients", "config"],
+  };
+
+/** Whether `<command> <sub> --help` is the subcommand's own to answer. */
+export function ownsSubcommandHelp(
+  command: string,
+  sub: string | undefined,
+): boolean {
+  return !!sub && (SUBCOMMAND_OWN_HELP[command] ?? []).includes(sub);
+}
+
 // Dash-flags each mutation subcommand accepts (global flags — -w/--workspace,
 // -t/--tabs/--no-tabs, --skip-secrets — are consumed by parseCliArgs before
 // dispatch, and -h/--help is handled by the dispatcher). Commands not listed

package/src/ui/cli/index.ts

@@ -193,6 +193,8 @@ import { cleanupStaleTabs } from "../../shared/cli-tabs.js";
 import { cmdConfig } from "./config-command.js";
 import { cmdEdge } from "./edge-command.js";
 import { cmdDoctor } from "./doctor-command.js";
+import { cmdSessions, SESSIONS_HELP } from "./sessions-command.js";
+import { AGENTS_HELP, cmdAgents } from "./agents-command.js";
 import { cmdService } from "./service-command.js";
 import { cmdStack } from "./stack-command.js";
 import { cmdTheme } from "./theme-command.js";
@@ -213,10 +215,12 @@ import {
 import { githubOrgFor } from "../../shared/environment-manager/workspace-org.js";
 import { cmdWeb, displayWebHelp } from "./web-command.js";
 import { cmdGraph } from "./graph-command.js";
+import { resolveTargetWorkspace } from "./target-workspace.js";
 import { resolveLogsTarget, tailServiceLogs } from "./logs-command.js";
 import {
   parseCliArgs,
   takeWorkspaceFlags,
+  ownsSubcommandHelp,
   unknownCommandFlags,
   workspaceFlagRequiresActive,
   type ParsedCliArgs,
@@ -309,19 +313,20 @@ const WORKSPACE_SUBCOMMANDS: {
 
 const COMMAND_HELP: Record<string, { usage: string; lines: string[] }> = {
   down: {
-    usage: "down [repo] [flags]",
+    usage: "down [repo] [-w <workspace>] [flags]",
     lines: [
       "Stop the cwd (or named) repo; --with-deps also stops what it sits on (its",
       "derived closure, in reverse order), naming anything else that uses it.",
       "-a/--all stops EVERY workspace system (reverse derived order, cwd-agnostic;",
       "every down script runs — no already-stopped skip).",
-      "Flags: -a/--all · -A/--app <app> · --with-deps · -n/--dry-run (print order, stop nothing) · --manifest (legacy depends_on)",
+      "Flags: -w/--workspace <ws> (that active workspace, not the focused one; focus stays) · -a/--all · -A/--app <app> · --with-deps · -n/--dry-run (print order, stop nothing) · --manifest (legacy depends_on)",
     ],
   },
   restart: {
-    usage: "restart [service...] [-A <app>] [-n|--dry-run]",
+    usage: "restart [service...] [-w <workspace>] [-A <app>] [-n|--dry-run]",
     lines: [
       `Restart the given services, or every repo in an application (\`${product().cli} apps\`).`,
+      "-w/--workspace <ws> acts in that active workspace instead of the focused one; focus stays.",
     ],
   },
   status: {
@@ -366,7 +371,7 @@ const COMMAND_HELP: Record<string, { usage: string; lines: string[] }> = {
   },
   setup: {
     usage:
-      "setup [service...] [--force|-f] [--plan [-w <workspace>]... [--all-active]]",
+      "setup [service...] [-w <workspace>] [--force|-f] [--plan [-w <workspace>]... [--all-active]]",
     lines: [
       "Run 'make setup' once per system (clones missing managed repos first).",
       "Default targets MANAGED clones only — setup's codegen/installs",
@@ -376,6 +381,7 @@ const COMMAND_HELP: Record<string, { usage: string; lines: string[] }> = {
       "cloned, seeded or written (on a fresh machine: the blueprint's plan).",
       "It plans the focused workspace; -w <workspace> (repeatable) plans those,",
       "--all-active every active one. Repos only other workspaces hold are named.",
+      "Without --plan, -w <workspace> sets up that workspace's systems instead of the focused one's.",
     ],
   },
   org: {
@@ -459,10 +465,14 @@ const COMMAND_HELP: Record<string, { usage: string; lines: string[] }> = {
     ],
   },
   doctor: {
-    usage: "doctor",
+    usage: "doctor [--probe]",
     lines: [
       "Each strategy kind (secrets, tls): the one selected, whether it was implicit,",
       "and whether it can work here (a PATH check; nothing is run or prompted).",
+      "--probe: start a short probe session (through the session host) for a",
+      "plain session and each available runtime's agent env; key names only.",
+      "Exit 1 when a runtime's scrubEnv name or a credential-shaped variable",
+      "reaches one. Without the PTY module it says unavailable, not failed.",
     ],
   },
   plugin: {
@@ -508,6 +518,8 @@ const COMMAND_HELP: Record<string, { usage: string; lines: string[] }> = {
     usage: "menu",
     lines: ["Open the interactive menu (pillar/module/env picker)."],
   },
+  sessions: SESSIONS_HELP,
+  agents: AGENTS_HELP,
 };
 
 function resolveCliBaseApiUrl(explicitBaseApiUrl?: string): string | undefined {
@@ -558,6 +570,8 @@ const TELEMETRY_COMMANDS = new Set<string>([
   "apps",
   "applications",
   "mcp",
+  "sessions",
+  "agents",
   "service",
   "theme",
   "plugin",
@@ -581,6 +595,10 @@ const CONFIG_FREE_COMMANDS = new Set<string>([
   "local-dev",
   "view-results",
   "down",
+  // The session host and its clients read no org data, and stopping or
+  // listing a session is never stranded by a config that fails (AG-3a).
+  "sessions",
+  "agents",
 ]);
 
 function configCheckedCommand(command: string): boolean {
@@ -780,10 +798,13 @@ class DenCLI {
 
     // `<command> -h/--help` → that command's help (every command supports it).
     // (`-h`/`--help` AS the command falls through to the switch → global help.)
+    // A subcommand that prints its own help (`web sessions --help`, `mcp
+    // connect --help`) is dispatched instead: its help wins.
     if (
       command &&
       !["-h", "--help", "-v", "--version"].includes(command) &&
-      (ownArgs.includes("-h") || ownArgs.includes("--help"))
+      (ownArgs.includes("-h") || ownArgs.includes("--help")) &&
+      !ownsSubcommandHelp(command, ownArgs[1])
     ) {
       this.printCommandHelp(command, ownArgs[1]);
       return;
@@ -964,7 +985,7 @@ class DenCLI {
           break;
 
         case "doctor":
-          process.exitCode = cmdDoctor(args.slice(1));
+          process.exitCode = await cmdDoctor(args.slice(1));
           break;
 
         case "service":
@@ -989,6 +1010,14 @@ class DenCLI {
           cmdApps(args.slice(1));
           break;
 
+        case "sessions":
+          process.exitCode = await cmdSessions(args.slice(1));
+          break;
+
+        case "agents":
+          process.exitCode = await cmdAgents(args.slice(1));
+          break;
+
         case "mcp": {
           // Setup subcommands: register the server with agents.
           const { MCP_CONNECT_SUBCOMMANDS, runMcpConnect } =
@@ -2709,6 +2738,10 @@ class DenCLI {
       "--manifest",
       `use legacy ${product().manifestYml} depends_on instead of the derived graph`,
     );
+    row(
+      "-w, --workspace <ws>",
+      "act in that (active) workspace instead of the focused one; focus stays",
+    );
     row("--skip-secrets", "skip the secrets-backend sign-in preflight");
     row("-h, --help", "show this help");
     console.log();
@@ -2954,7 +2987,44 @@ class DenCLI {
     }
   }
 
+  /**
+   * With no `-w`: the workspace the named services are in, when it isn't
+   * the focus (target-workspace.ts), set as this run's workspace. False
+   * (exit 1, said why) when a name is in no active workspace, in several,
+   * or the names are in different ones.
+   */
+  private pickTargetWorkspace(command: string, args: string[]): boolean {
+    if (process.env.DEN_WORKSPACE_OVERRIDE) return true;
+    const terminator = args.indexOf("--");
+    const own = terminator === -1 ? args : args.slice(0, terminator);
+    let rest: string[];
+    try {
+      const taken = takeAppFlag(own);
+      if (taken.app) return true; // -A names an application, not services
+      rest = taken.rest;
+    } catch {
+      return true; // the command itself reports a bad -A
+    }
+    const names = rest.filter((a) => !a.startsWith("-"));
+    const r = resolveTargetWorkspace(names, product().cli, command);
+    if (!r.ok) {
+      console.error(chalk.red(`\n  ✗ ${r.error}\n`));
+      process.exitCode = 1;
+      return false;
+    }
+    if (r.workspace) {
+      process.env.DEN_WORKSPACE_OVERRIDE = r.workspace;
+      console.log(
+        chalk.gray(
+          `\n  ${names.join(", ")}: in workspace ${r.workspace} (not the focus)`,
+        ),
+      );
+    }
+    return true;
+  }
+
   private async cmdServiceUp(args: string[]): Promise<void> {
+    if (!this.pickTargetWorkspace("up", args)) return;
     // Tokens after a `--` terminator belong to a child command — they must
     // never be read as up's own flags (`den up -- -a` is NOT `up -a`).
     const terminator = args.indexOf("--");
@@ -3079,6 +3149,7 @@ class DenCLI {
   }
 
   private async cmdServiceDown(args: string[]): Promise<void> {
+    if (!this.pickTargetWorkspace("down", args)) return;
     // Tokens after a `--` terminator belong to a child command — they must
     // never be read as down's own flags (`den down -- -a` must NOT tear
     // down the whole workspace).
@@ -3149,6 +3220,7 @@ class DenCLI {
   }
 
   private async cmdServiceRestart(argv: string[]): Promise<void> {
+    if (!this.pickTargetWorkspace("restart", argv)) return;
     const { app, rest: args } = takeAppFlag(argv);
     const dryRun = args.includes("--dry-run") || args.includes("-n");
     if (!dryRun) preflightSecrets();
@@ -4046,15 +4118,33 @@ class DenCLI {
       console.log();
       return;
     }
-    if (planWs.length || allActive) {
+    if (planWs.length > 1 || allActive) {
       console.error(
         chalk.red(
-          `\n  -w and --all-active go with --plan: setup itself works on the focused workspace.\n`,
+          `\n  More than one -w, and --all-active, go with --plan: setup itself works on one workspace (-w <workspace>, or the one the named repos are in, else the focus).\n`,
         ),
       );
       process.exitCode = 1;
       return;
     }
+    if (planWs.length === 1) {
+      const ws = planWs[0];
+      if (!readWorkspacesFile().workspaces[ws]) {
+        console.error(chalk.red(`\n  Workspace "${ws}" does not exist\n`));
+        process.exitCode = 1;
+        return;
+      }
+      if (!isWorkspaceActive(ws)) {
+        console.error(
+          chalk.red(
+            `\n  Workspace "${ws}" is not active — run \`${product().cli} workspace activate ${ws}\` first\n`,
+          ),
+        );
+        process.exitCode = 1;
+        return;
+      }
+      process.env.DEN_WORKSPACE_OVERRIDE = ws;
+    } else if (!this.pickTargetWorkspace("setup", args)) return;
 
     // Clone any managed repos that aren't on disk yet before reading manifests.
     this.cloneMissingManagedRepos();
@@ -4069,11 +4159,27 @@ class DenCLI {
       return;
     }
 
+    // A name the listing doesn't spell the same way (an alias, a bare repo
+    // listed only by subsystem) is matched as resolveService resolves it.
+    const matches = (name: string, s: (typeof services)[number]): boolean => {
+      if (name === s.address || name === s.repoName) return true;
+      const r = resolveService(name);
+      return !!r && (r.address === s.address || r.repoName === s.address);
+    };
+    const unmatched = names.filter((n) => !services.some((s) => matches(n, s)));
+    if (unmatched.length > 0) {
+      const ws = getActiveWorkspace()?.name ?? "default";
+      console.error(
+        chalk.red(
+          `\n  ✗ Not in workspace ${ws}: ${unmatched.join(", ")}. Nothing was set up.\n`,
+        ),
+      );
+      process.exitCode = 1;
+      return;
+    }
     let targets =
       names.length > 0
-        ? services.filter(
-            (s) => names.includes(s.address) || names.includes(s.repoName),
-          )
+        ? services.filter((s) => names.some((n) => matches(n, s)))
         : services;
 
     // Workspace-wide default: MANAGED clones only. `make setup` runs
@@ -4805,6 +4911,16 @@ class DenCLI {
     console.log(
       "  plugin list          Local and added plugins, checked (validate, add, update, remove)",
     );
+    console.log(
+      "  sessions start -w <ws> --name <n> -- <argv…>  A terminal that outlives the web server",
+    );
+    console.log(
+      "  sessions list|attach|kill   List, attach to (ctrl-] detaches) or stop sessions",
+    );
+    console.log("  agents list -w <ws>  The workspace's agents");
+    console.log(
+      "  agents start -w <ws> --persona <p>  Run a persona in the workspace (stop, resume, personas)",
+    );
     console.log();
     console.log(
       "  workspace list           List workspaces (active set + focus)",