@monster-orange/den 0.4.21 → 0.4.22

package/src/shared/launchd-session.ts

@@ -0,0 +1,92 @@
+/**
+ * D20: the launchd session a process runs in, as `launchctl managername`
+ * names it. It decides what survives a logout:
+ *
+ *   Aqua, LoginWindow  the desktop login session (gui/<uid>): ends when the
+ *                      person logs out, with every process in it.
+ *   Background         outside it (an ssh shell, user/<uid>): keeps running
+ *                      after logout, but has no login keychain and no GUI
+ *                      (headed apps, WebKit on macOS).
+ *   System             a LaunchDaemon: as Background.
+ *
+ * A child inherits its parent's session, so a session host started from
+ * the desktop dies at logout with every agent in it. Off macOS there is no
+ * such thing (null).
+ */
+import { spawnSync } from "child_process";
+
+/**
+ * `service install --mode always` is opt-in: it is meant to keep the
+ * server, the host and every agent running across a logout, but no logout
+ * has proven it yet. Every place that offers it says so.
+ */
+export const ALWAYS_UNPROVEN = "not yet proven across a logout";
+
+export type LaunchctlRunner = () => { status: number | null; stdout: string };
+
+const defaultRunner: LaunchctlRunner = () => {
+  const r = spawnSync("launchctl", ["managername"], {
+    encoding: "utf-8",
+    timeout: 2000,
+  });
+  return { status: r.status, stdout: r.stdout ?? "" };
+};
+
+/** `launchctl managername`, or "unknown"; null off macOS. */
+export function readLaunchdSession(
+  run: LaunchctlRunner = defaultRunner,
+  platform: NodeJS.Platform = process.platform,
+): string | null {
+  if (platform !== "darwin") return null;
+  try {
+    const r = run();
+    const name = r.status === 0 ? r.stdout.trim() : "";
+    // Only a plain word: it is shown and stored as-is.
+    return /^[A-Za-z]{1,32}$/.test(name) ? name : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+let cached: string | null | undefined;
+
+/** This process's launchd session (it never changes, so asked once). */
+export function launchdSession(): string | null {
+  if (cached === undefined) cached = readLaunchdSession();
+  return cached;
+}
+
+/**
+ * D20: `web up` from a shell outside the desktop session (an ssh shell:
+ * Background) starts a server there; say what that means and the right
+ * way. null in the desktop session or off macOS.
+ */
+export function webUpWarning(
+  session: string | null | undefined,
+  cli: string,
+): string | null {
+  if (session !== "Background" && session !== "System") return null;
+  return `this shell runs outside the desktop session (${session}, e.g. ssh): a server started here keeps running after logout but has no login keychain and no GUI, and its agents run here too. To run it as a service: ${cli} service install --mode always (opt-in, ${ALWAYS_UNPROVEN}) or --mode login`;
+}
+
+/** Whether a process in this session ends when the person logs out. */
+export function endsAtLogout(session: string | null | undefined): boolean {
+  return session === "Aqua" || session === "LoginWindow";
+}
+
+/**
+ * The line doctor and the agent page show for `what` (the server, the
+ * session host, an agent) running in `session`: the fix when it ends at
+ * logout, what it lacks when it doesn't. null when there is nothing to say.
+ */
+export function sessionWarning(
+  session: string | null | undefined,
+  cli: string,
+  what: string,
+): string | null {
+  if (endsAtLogout(session))
+    return `the ${what} runs in the desktop login session (${session}): it stops when you log out. To keep it running: ${cli} service install --mode always (opt-in, ${ALWAYS_UNPROVEN})`;
+  if (session === "Background" || session === "System")
+    return `the ${what} keeps running after logout (${session}); it has no login keychain and no GUI, so it uses the 1Password service-account token, headless browsers and Full Disk Access instead`;
+  return null;
+}

package/src/shared/sessions/client.ts

@@ -45,6 +45,8 @@ export class HostClient extends EventEmitter {
   private readonly attachments = new Map<string, AttachHandlers>();
   hostPid = 0;
   hostStartedAt = "";
+  /** D20: the host's launchd session (null off macOS or an older host). */
+  hostLaunchd: string | null = null;
 
   constructor(private readonly socket: net.Socket) {
     super();
@@ -117,10 +119,32 @@ export class HostClient extends EventEmitter {
     this.request(op, body).catch(() => undefined);
   }
 
+  /**
+   * D18: the host's executable and whether it has Full Disk Access (null:
+   * cannot tell). null from a host older than 0.4.22.
+   */
+  async access(): Promise<{
+    exe: string;
+    fullDiskAccess: boolean | null;
+  } | null> {
+    try {
+      const r = await this.request("access");
+      return {
+        exe: String(r.exe ?? ""),
+        fullDiskAccess:
+          typeof r.fullDiskAccess === "boolean" ? r.fullDiskAccess : null,
+      };
+    } catch (e) {
+      if (e instanceof HostError && e.code === "bad-request") return null;
+      throw e;
+    }
+  }
+
   async hello(): Promise<void> {
     const r = await this.request("hello");
     this.hostPid = Number(r.pid);
     this.hostStartedAt = String(r.startedAt ?? "");
+    this.hostLaunchd = typeof r.launchd === "string" ? r.launchd : null;
   }
 
   async start(

package/src/shared/sessions/host.ts

@@ -29,6 +29,7 @@ import {
   type Request,
 } from "./protocol.js";
 import type { PtyLoad, PtyProcess } from "./pty.js";
+import { launchdSession } from "../launchd-session.js";
 import {
   SESSION_POOLS,
   SESSION_SIGNALS,
@@ -54,6 +55,14 @@ export interface SessionHostOptions {
   log?: (line: string) => void;
   /** Called after a `shutdown` request has closed the host. */
   onShutdown?: () => void;
+  /** D20: the launchd session it runs in (default: asked; null off macOS). */
+  launchdSession?: string | null;
+  /**
+   * D18: whether this process has Full Disk Access (default: it can list
+   * macOS's TCC folder, which only such a process can; null off macOS).
+   * What it starts inherits it, so the agents have it too.
+   */
+  fullDiskAccess?: () => boolean | null;
 }
 
 interface Session {
@@ -169,6 +178,27 @@ function printableActor(v: unknown): string {
 
 const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
 
+/**
+ * D18: Full Disk Access, as macOS grants it to this executable: only such
+ * a process may list ~/Library/Application Support/com.apple.TCC. null off
+ * macOS, or when the folder is not there to ask.
+ */
+export function hasFullDiskAccess(
+  home: string = process.env.HOME ?? "",
+  platform: NodeJS.Platform = process.platform,
+): boolean | null {
+  if (platform !== "darwin" || !home) return null;
+  try {
+    fs.readdirSync(
+      path.join(home, "Library", "Application Support", "com.apple.TCC"),
+    );
+    return true;
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code;
+    return code === "EPERM" || code === "EACCES" ? false : null;
+  }
+}
+
 export class SessionHost {
   readonly paths: SessionPaths;
   private readonly sessions = new Map<string, Session>();
@@ -176,9 +206,17 @@ export class SessionHost {
   private server: net.Server | null = null;
   private readonly startedAt = new Date().toISOString();
   private closed = false;
+  /** D20: where it runs; stamped on every session it starts. */
+  private readonly launchd: string | null;
 
   constructor(private readonly opts: SessionHostOptions) {
     this.paths = sessionPaths(opts.stateDir);
+    const where =
+      opts.launchdSession !== undefined
+        ? opts.launchdSession
+        : launchdSession();
+    // "unknown" (launchctl said nothing) is no stamp at all.
+    this.launchd = where === "unknown" ? null : where;
   }
 
   private log(line: string): void {
@@ -189,6 +227,34 @@ export class SessionHost {
     return this.opts.scrollbackBytes ?? DEFAULT_SCROLLBACK_BYTES;
   }
 
+  /**
+   * Calls `onGone` once its state dir no longer exists (checked every
+   * `everyMs`): nothing it owns can be kept any more, so the host should
+   * end. A test that deletes its temp state dir no longer leaves a host
+   * running; a real install never deletes its state dir under a running
+   * host. Returns a stop function.
+   */
+  watchStateDir(everyMs: number, onGone: () => void): () => void {
+    const t = setInterval(() => {
+      if (fs.existsSync(this.opts.stateDir)) return;
+      clearInterval(t);
+      onGone();
+    }, everyMs);
+    t.unref();
+    return () => clearInterval(t);
+  }
+
+  /**
+   * D18: serve once no other host answers on the socket, checking every
+   * `everyMs`; resolves once it listens.
+   */
+  async listenWhenFree(everyMs: number): Promise<"listening"> {
+    for (;;) {
+      if ((await this.listen()) === "listening") return "listening";
+      await sleep(everyMs);
+    }
+  }
+
   /** Serve on the socket, or stand down when a host already answers there. */
   async listen(): Promise<"listening" | "already-running"> {
     const { socket } = this.paths;
@@ -293,6 +359,7 @@ export class SessionHost {
           exited?: boolean;
           exitCode?: number;
           prompted?: boolean;
+          launchd?: unknown;
         };
         if (typeof rec.id !== "string" || typeof rec.name !== "string")
           continue;
@@ -308,6 +375,10 @@ export class SessionHost {
               ? { exitCode: rec.exitCode }
               : {}),
             ...(rec.prompted === true ? { prompted: true } : {}),
+            ...(typeof rec.launchd === "string" &&
+            /^[A-Za-z]{1,32}$/.test(rec.launchd)
+              ? { launchd: rec.launchd }
+              : {}),
           },
           cwd: rec.cwd,
           pty: null,
@@ -338,6 +409,7 @@ export class SessionHost {
       ...(s.info.exited ? { exited: true } : {}),
       ...(s.info.exitCode !== undefined ? { exitCode: s.info.exitCode } : {}),
       ...(s.info.prompted ? { prompted: true } : {}),
+      ...(s.info.launchd ? { launchd: s.info.launchd } : {}),
     };
     try {
       fs.writeFileSync(
@@ -419,6 +491,7 @@ export class SessionHost {
           v: PROTOCOL_VERSION,
           pid: process.pid,
           startedAt: this.startedAt,
+          launchd: this.launchd,
         };
       case "list":
         return {
@@ -498,6 +571,12 @@ export class SessionHost {
         this.forget(s);
         return {};
       }
+      case "access":
+        // D18: what this host (and every agent in it) may reach.
+        return {
+          exe: process.execPath,
+          fullDiskAccess: (this.opts.fullDiskAccess ?? hasFullDiskAccess)(),
+        };
       default:
         throw new Refusal("bad-request", `unknown op "${String(req.op)}"`);
     }
@@ -607,6 +686,7 @@ export class SessionHost {
         name,
         pid: pty.pid,
         startedAt: new Date().toISOString(),
+        ...(this.launchd ? { launchd: this.launchd } : {}),
       },
       cwd,
       pty,
@@ -712,7 +792,19 @@ export class SessionHost {
  * already running; 1 when it cannot listen.
  */
 export async function runSessionHost(
-  opts: Omit<SessionHostOptions, "onShutdown">,
+  opts: Omit<SessionHostOptions, "onShutdown"> & {
+    /**
+     * D18: the launchd job's host. While another host answers on the
+     * socket (one started before the job, from a terminal or the web
+     * server), wait for it to end, then serve, instead of exiting at once
+     * (launchd would restart it every few seconds). Checks every
+     * standByMs (default 5 s).
+     */
+    standBy?: boolean;
+    standByMs?: number;
+    /** How often it checks its state dir still exists (default 10 s). */
+    stateDirCheckMs?: number;
+  },
 ): Promise<number> {
   const log =
     opts.log ??
@@ -729,15 +821,32 @@ export async function runSessionHost(
     log(`session host could not start: ${(e as Error).message}`);
     return 1;
   }
-  if (state === "already-running") {
+  const stop = () => void host.close().then(() => process.exit(0));
+  if (state === "already-running" && opts.standBy) {
+    process.on("SIGTERM", stop);
+    process.on("SIGINT", stop);
+    log(
+      `a session host is already running on ${host.paths.socket}: standing by until it ends (its sessions keep running there)`,
+    );
+    try {
+      state = await host.listenWhenFree(opts.standByMs ?? 5000);
+    } catch (e) {
+      log(`session host could not start: ${(e as Error).message}`);
+      return 1;
+    }
+  } else if (state === "already-running") {
     log(`a session host is already running on ${host.paths.socket}`);
     return 0;
+  } else {
+    process.on("SIGTERM", stop);
+    process.on("SIGINT", stop);
   }
-  const stop = () => void host.close().then(() => process.exit(0));
-  process.on("SIGTERM", stop);
-  process.on("SIGINT", stop);
   // No terminal to hang up on: it was started detached.
   process.on("SIGHUP", () => undefined);
   log(`session host ${process.pid} listening on ${host.paths.socket}`);
+  host.watchStateDir(opts.stateDirCheckMs ?? 10_000, () => {
+    log(`its state dir ${opts.stateDir} is gone: stopping`);
+    stop();
+  });
   return 0;
 }

package/src/shared/sessions/types.ts

@@ -30,6 +30,11 @@ export interface SessionInfo {
    * starts afresh instead. Never what was typed.
    */
   prompted?: boolean;
+  /**
+   * D20: the launchd session its host ran in (`launchctl managername`):
+   * Aqua ends at logout, Background survives it. Absent off macOS.
+   */
+  launchd?: string;
 }
 
 /**

package/src/ui/cli/agent-ops.ts

@@ -71,7 +71,10 @@ import {
   type CatalogEntry,
 } from "../../shared/agents/catalog.js";
 import { checkRuntimeBin } from "../../shared/agents/catalog-runtime.js";
-import { agentSessionName } from "../../shared/agents/session-name.js";
+import {
+  agentSessionName,
+  peerSessionName,
+} from "../../shared/agents/session-name.js";
 import { cliEntrypoint } from "../../shared/engine.js";
 import { getDistRoot } from "../../shared/paths.js";
 import { envKey } from "../../shared/product.js";
@@ -1637,11 +1640,17 @@ export async function startAgent(
     );
   ptyOrRefuse(d);
   const allow = allowedFor(d, persona, ch.extras);
+  // D24: the name peers see it by, from the name it will have (below).
+  const peerName = peerSessionName(d.cli, ws, {
+    id,
+    displayName: given ?? prev?.displayName ?? persona.displayName,
+  });
   const input = {
     ...launchInput(d, cfg, persona, ws, id, model, det.path, undefined, {
       ...(ch.permission ? { permission: ch.permission } : {}),
       ...(rt.permissions ? { allow } : {}),
     }),
+    sessionLabel: peerName,
     ...(more.firstPrompt ? { firstPrompt: more.firstPrompt } : {}),
     // 0.4.18: Start agent here: in a folder of the workspace's.
     ...(req.folder !== undefined && !more.bringIn
@@ -1699,6 +1708,7 @@ export async function startAgent(
           workspace: ws,
           cwd: input.worktree,
           sessionName: sessionName(d.dist, ws, id),
+          peerName,
           // AG-4b: a name given to the agent is the agent's, not its
           // conversation's: Start fresh and Relaunch keep it. AG-10.8:
           // else its persona's name ("Rita").
@@ -2175,8 +2185,11 @@ export async function resumeAgent(
       },
     );
     // Resume in the cwd the agent had, wherever the workspace points now.
+    // D24 (and D25: a rename since) the name peers see it by.
+    const peerName = peerSessionName(d.cli, rec.workspace, rec);
     const at = {
       ...input,
+      sessionLabel: peerName,
       worktree: rec.cwd,
       ...(rec.resumeToken ? { resumeToken: rec.resumeToken } : {}),
     };
@@ -2211,7 +2224,12 @@ export async function resumeAgent(
         d,
         c,
         {
-          rec: { ...base, cwd: rec.cwd, ...(token ? { launched: true } : {}) },
+          rec: {
+            ...base,
+            cwd: rec.cwd,
+            peerName,
+            ...(token ? { launched: true } : {}),
+          },
           argv: out.argv,
           env: out.env,
           passthrough: rt.envPassthrough,

package/src/ui/cli/agents-command.ts

@@ -87,6 +87,7 @@ import {
   relaunchAgent,
   removeAgent,
   removeStopped,
+  renameAgent,
   resolveAgentsDeps,
   resumeAgent,
   resumeInterrupted,
@@ -99,6 +100,7 @@ import {
   type RuntimeChoice,
   type Started,
 } from "./agent-ops.js";
+import { peerSessionName } from "../../shared/agents/session-name.js";
 import {
   columns,
   guarded,
@@ -119,7 +121,7 @@ export {
 
 export const AGENTS_HELP = {
   usage:
-    "agents <list|start|stop|resume|relaunch|import|persona|rm|personas|doctor|handback-check|handoff-check> ...",
+    "agents <list|start|stop|resume|relaunch|import|persona|rename|rm|personas|doctor|handback-check|handoff-check> ...",
   lines: [
     "Agents: a persona and a workspace, run by a runtime in a session that",
     "outlives the web server (see `{cli} sessions`).",
@@ -156,6 +158,11 @@ export const AGENTS_HELP = {
     "    persona's role, permissions and commands; id, name, folder and model stay.",
     "    Mid-turn it asks: --after-turn waits for the turn to end, --now stops it.",
     "    A person's only (refused in an agent's session)",
+    "{cli} agents rename <id> <name> [-w <ws>]",
+    "{cli} agents rename <id> --clear [-w <ws>]",
+    "    name an agent (its tab, row and pane header); the id never changes.",
+    "    Other sessions see it as {cli}-<ws>:<name> from its next start or resume.",
+    "    --clear: back to its id",
     "{cli} agents rm <id> [-w <ws>]",
     "{cli} agents rm --stopped [-w <ws>]",
     "    forget a stopped, interrupted or exited agent (never a running one);",
@@ -513,6 +520,28 @@ async function resumeAll(args: string[], d: AgentsResolved): Promise<number> {
 }
 
 /** `agents rm <id> [-w <ws>]`, `agents rm --stopped [-w <ws>]` (AG-14.1b). */
+/** D25: `agents rename <id> <name>|--clear [-w <ws>]`. */
+function rename(args: string[], d: AgentsResolved): number {
+  const where = "agents rename";
+  const p = parseArgs(where, args, { "--workspace": true, "--clear": false });
+  const [id, ...words] = p.positional;
+  if (!id) throw new UsageError(`${where} needs <id> and a name, or --clear`);
+  const name = words.join(" ").trim();
+  if (p.flags["--clear"] && name)
+    throw new UsageError(`${where}: give a name or --clear, not both`);
+  if (!p.flags["--clear"] && !name)
+    throw new UsageError(`${where} needs a name (or --clear)`);
+  const ws =
+    workspaceFlag(where, p) ?? readRecord(d.stateDir(), id)?.workspace ?? "";
+  const rec = renameAgent(d, id, ws, p.flags["--clear"] ? null : name);
+  d.out(
+    rec.displayName
+      ? `renamed agent ${id} to "${rec.displayName}"; others see it as ${peerSessionName(d.cli, rec.workspace, rec)} from its next start or resume`
+      : `agent ${id} has no name now; others see it as ${peerSessionName(d.cli, rec.workspace, rec)} from its next start or resume`,
+  );
+  return 0;
+}
+
 async function rm(args: string[], d: AgentsResolved): Promise<number> {
   const where = "agents rm";
   const p = parseArgs(where, args, { "--workspace": true, "--stopped": false });
@@ -767,6 +796,8 @@ export async function cmdAgents(
         case "persona":
           await loadAgentWorkspaces(deps);
           return await persona(rest, d);
+        case "rename":
+          return rename(rest, d);
         case "rm":
           await loadAgentWorkspaces(deps);
           return await rm(rest, d);

package/src/ui/cli/doctor-command.ts

@@ -67,6 +67,13 @@ import {
 } from "./doctor-onboard.js";
 import { printJson } from "./json-out.js";
 import { ownerCheck, ownerLine } from "./doctor-owner.js";
+import {
+  formatWhere,
+  serviceJobState,
+  whereRows,
+  type WhereDeps,
+  type WhereRow,
+} from "./doctor-where.js";
 
 export interface DoctorRow {
   kind: string;
@@ -387,6 +394,62 @@ export async function doctorJson(
   return { ok: !checks.some((c) => c.status === "fail"), checks };
 }
 
+/** D18/D20: the real probes for doctor's "where it runs" rows. */
+export async function defaultWhereDeps(): Promise<WhereDeps> {
+  const os = await import("os");
+  const { readDenConfig: cfg, readWebServiceConfig } =
+    await import("../../shared/den-config.js");
+  const { readWebPort } = await import("../../shared/edge/config.js");
+  const { getDistRoot } = await import("../../shared/paths.js");
+  const { connectHost } = await import("../../shared/sessions/client.js");
+  const { sessionPaths } = await import("../../shared/sessions/paths.js");
+  return {
+    cli: product().cli,
+    platform: process.platform,
+    server: async () => {
+      const port = readWebPort(getDistRoot());
+      const res = await fetch(`http://localhost:${port}/api/server-info`, {
+        signal: AbortSignal.timeout(1500),
+      });
+      if (!res.ok) return null;
+      const body = (await res.json()) as { launchd?: string | null };
+      return { launchd: body.launchd ?? null };
+    },
+    host: async () => {
+      const c = await connectHost(sessionPaths(getStateDir()).socket);
+      try {
+        return {
+          launchd: c.hostLaunchd,
+          access: await c.access().catch(() => null),
+        };
+      } finally {
+        c.close();
+      }
+    },
+    service: () => {
+      try {
+        const { label } = readWebServiceConfig(
+          cfg(),
+          getDistRoot(),
+          os.homedir(),
+        );
+        return serviceJobState(label, os.homedir(), process.getuid?.() ?? 0);
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+/** A "where it runs" row as a `doctor --json` check. */
+export function whereCheck(r: WhereRow): OnboardCheck {
+  return {
+    id: `where:${r.what.replace(" ", "-")}`,
+    status: r.status,
+    detail: `${r.session}${r.detail ? `: ${r.detail}` : ""}`,
+  };
+}
+
 export async function cmdDoctor(args: string[]): Promise<number> {
   const probe = args.includes("--probe");
   const json = args.includes("--json");
@@ -415,6 +478,9 @@ export async function cmdDoctor(args: string[]): Promise<number> {
     const r = await doctorJson(
       defaultOnboardDeps((url) => probeWebServer(url)),
     );
+    r.checks.push(
+      ...(await whereRows(await defaultWhereDeps())).map(whereCheck),
+    );
     printJson(r);
     return r.ok ? 0 : 1;
   }
@@ -427,6 +493,12 @@ export async function cmdDoctor(args: string[]): Promise<number> {
   console.log("");
   console.log(ownerLine(owner));
   const ownerProblem = owner.status === "fail";
+  // D18/D20: where the server and the session host run (logout).
+  for (const l of formatWhere(
+    await whereRows(await defaultWhereDeps()),
+    readBrand().name,
+  ))
+    console.log(l);
   for (const l of pollingLines(eventsFile(), readBrand().name)) console.log(l);
   const cli = product().cli;
   if (!probe) {