chamba 0.3.1 → 0.5.0

package/dist/lib/safe-rm.js

@@ -0,0 +1,26 @@
+// =========================================================================================================================================
+// src/lib/safe-rm.ts - Safe wrapper around rmSync
+// All deletions in chamba go through safeRmSync. A biome lint rule (noRestrictedImports) bans
+// importing rmSync from node:fs everywhere else, enforcing this as the single deletion point.
+// =========================================================================================================================================
+// biome-ignore lint/style/noRestrictedImports: safeRmSync is the only approved user of rmSync
+import { rmSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { basename, join, resolve, sep } from "node:path";
+import { CHAMBA_DIR, CHAMBA_YAML, CONTAINER_NAME_PREFIX } from "./constants.js";
+const CHAMBA_HOME = resolve(join(homedir(), CHAMBA_DIR));
+const TEST_TMP_PREFIX = join(tmpdir(), `${CONTAINER_NAME_PREFIX}test-`);
+/**
+ * Safe wrapper around rmSync. Throws if the path is outside a chamba-owned location:
+ *   - ~/.chamba/            (workspace caches, agents, shadows, global config)
+ *   - A file named chamba.yaml  (workspace config file in any user workspace root)
+ *   - <tmpdir>/chamba-test-*   (test temp directories)
+ */
+export function safeRmSync(path, options) {
+    const r = resolve(path);
+    const ok = r === CHAMBA_HOME || r.startsWith(CHAMBA_HOME + sep) || basename(r) === CHAMBA_YAML || r.startsWith(TEST_TMP_PREFIX);
+    if (!ok) {
+        throw new Error(`safeRmSync: refusing to delete '${r}' - must be under ~/.chamba/, named chamba.yaml, or a test temp dir`);
+    }
+    rmSync(r, options);
+}

package/dist/lib/sessions.js

@@ -0,0 +1,34 @@
+// =========================================================================================================================================
+// src/lib/sessions.ts - Host-side detection of live interactive container sessions.
+// dev.ts connects each session with `docker exec -it ... <container> bash --login`. The host-side exec
+// client process is the proxy for one live session: it dies on clean exit, closed terminal, or kill, but
+// survives a sleep-freeze. Orphaned in-container shells (host side gone, PTY left open by dockerd) have no
+// host client and are correctly ignored - which is why counting on the host, not inside the container, is
+// the reliable signal for "last session closed".
+// =========================================================================================================================================
+import { spawnSync } from "node:child_process";
+// The interactive session shell, as argv. Single source of truth: both the connect command and the
+// detector's match needle derive from this, so they cannot drift apart.
+export const CONTAINER_LOGIN_SHELL = ["bash", "--login"];
+// --- Connect -----------------------------------------------------------------------------------------------------------------------------
+// Build the `docker exec` argv that opens an interactive session in `containerName` at `workdir`.
+// dev.ts spawns exactly this; sessionMatchNeedle matches against it, so detection stays in lockstep.
+export function loginShellExecArgs(workdir, containerName) {
+    return ["exec", "-it", "-w", workdir, containerName, ...CONTAINER_LOGIN_SHELL];
+}
+// --- Detection ---------------------------------------------------------------------------------------------------------------------------
+// The substring identifying one container's session client in a host `pgrep -f` scan: the container name
+// followed by the login shell args (e.g. "chamba-orot-io bash --login"). Specific enough to exclude other
+// `docker exec <c> ...` shapes. Container ids are kebab-case (schema-constrained), so there are no regex
+// metacharacters to escape.
+export function sessionMatchNeedle(containerName) {
+    return `${containerName} ${CONTAINER_LOGIN_SHELL.join(" ")}`;
+}
+// Count live interactive sessions to a single container by scanning HOST processes for the exec client.
+// `pgrep -f` (portable across macOS/BSD and Linux; `-c` is Linux-only) excludes its own PID. A missing or
+// errored pgrep yields no stdout -> 0, preserving the old "errored -> 0" safety. At a clean exit the just-
+// left client is already reaped before this runs, so the last exit reaches 0.
+export function containerSessionCount(containerName) {
+    const r = spawnSync("pgrep", ["-f", sessionMatchNeedle(containerName)], { encoding: "utf8", stdio: "pipe" });
+    return (r.stdout ?? "").split("\n").filter(Boolean).length;
+}

package/dist/lib/shadows.js

@@ -0,0 +1,174 @@
+// =========================================================================================================================================
+// src/lib/shadows.ts - Gitignore-style shadow path expansion and sync
+// Expands patterns like "node_modules", ".env*" into concrete paths, then syncs shadow directories.
+// =========================================================================================================================================
+import { spawnSync } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import fg from "fast-glob";
+import { CONTAINER_WORKSPACE, SHADOWS_DIR } from "./constants.js";
+import { safeRmSync } from "./safe-rm.js";
+/**
+ * Expand gitignore-style patterns into concrete relative paths.
+ *
+ * Patterns without a directory separator are treated as recursive (prepended with **/)
+ * following gitignore convention. Patterns with a / are matched relative to the workspace root.
+ * Matched directories are not recursed into (e.g. node_modules matches once, not its children).
+ *
+ * Paths that git tracks (or whose descendants git tracks) are dropped from the result and
+ * reported in skippedTracked. Shadowing tracked content is a no-op (agents can `git show` it)
+ * and breaks `git stash`/`pop` workflows.
+ */
+export function expandShadowPatterns(patterns, workspaceRoot) {
+    if (patterns.length === 0)
+        return { paths: [], skippedTracked: [] };
+    // Convert gitignore-style patterns to fast-glob patterns
+    const globPatterns = patterns.map((p) => (p.includes("/") ? p : `**/${p}`));
+    // Build ignore list: skip .git and contents of any matched directory
+    const ignorePatterns = ["**/.git", ...globPatterns.map((p) => `${p}/**/*`)];
+    const results = fg.sync(globPatterns, {
+        cwd: workspaceRoot,
+        onlyFiles: false,
+        dot: true,
+        ignore: ignorePatterns,
+    });
+    const expanded = removeNestedPaths(results.sort());
+    const { kept, dropped } = filterGitTrackedPaths(expanded, workspaceRoot);
+    return { paths: kept, skippedTracked: dropped };
+}
+// --- Hit counting (for menu UX) ----------------------------------------------------------------------------------------------------------
+/** Count how many paths a pattern would match in the workspace (post git-tracked filter). */
+export function countPatternHits(pattern, workspaceRoot) {
+    return expandShadowPatterns([pattern], workspaceRoot).paths.length;
+}
+// --- Git-tracked filtering ---------------------------------------------------------------------------------------------------------------
+/**
+ * Partition expanded shadow paths into those safe to shadow and those tracked by git.
+ * A path is dropped if it equals a tracked file, or (for directories) any tracked file
+ * lives anywhere beneath it. Returns the input unchanged when no .git is present.
+ */
+function filterGitTrackedPaths(paths, workspaceRoot) {
+    if (paths.length === 0)
+        return { kept: [], dropped: [] };
+    // .git may be a file (worktrees) or a directory; existsSync handles both
+    if (!existsSync(join(workspaceRoot, ".git")))
+        return { kept: paths, dropped: [] };
+    // Pass shadow paths as pathspecs so git enumerates only tracked files within them.
+    // Output then scales with shadow scope (typically tiny), not the size of the repo index.
+    const result = spawnSync("git", ["-C", workspaceRoot, "ls-files", "-z", "--", ...paths], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (result.status !== 0)
+        return { kept: paths, dropped: [] };
+    const matched = result.stdout.split("\0").filter((s) => s.length > 0);
+    if (matched.length === 0)
+        return { kept: paths, dropped: [] };
+    const matchedSet = new Set(matched);
+    const kept = [];
+    const dropped = [];
+    for (const p of paths) {
+        const prefix = `${p}/`;
+        if (matchedSet.has(p) || matched.some((f) => f.startsWith(prefix))) {
+            dropped.push(p);
+        }
+        else {
+            kept.push(p);
+        }
+    }
+    return { kept, dropped };
+}
+// --- Shadow sync -------------------------------------------------------------------------------------------------------------------------
+/**
+ * Ensures the shadows/ directory matches the given expanded paths.
+ * - Creates missing shadow entries (empty dir or empty file, matching source path type)
+ * - If `freshPaths` is provided, those entries are deleted and recreated (clean slate)
+ * - Removes shadow entries not in the expanded set
+ * - Cleans up empty parent directories
+ */
+export function ensureShadowsInSync(workspaceDir, expandedPaths, workspaceRoot, freshPaths) {
+    const expected = new Set(expandedPaths);
+    const shadowsDir = join(workspaceDir, SHADOWS_DIR);
+    // Create shadows/ root if needed
+    mkdirSync(shadowsDir, { recursive: true });
+    // Remove stale entries
+    removeStaleEntries(shadowsDir, shadowsDir, expected);
+    // Create or refresh expected entries
+    for (const relPath of expected) {
+        const sourcePath = join(workspaceRoot, relPath);
+        const shadowPath = join(shadowsDir, relPath);
+        if (freshPaths?.has(relPath) && existsSync(shadowPath)) {
+            safeRmSync(shadowPath, { recursive: true, force: true });
+        }
+        if (!existsSync(shadowPath)) {
+            createShadowEntry(sourcePath, shadowPath);
+        }
+    }
+}
+// --- Mount args --------------------------------------------------------------------------------------------------------------------------
+/** Build -v args for shadow mounts from expanded paths. */
+export function buildShadowMountArgs(workspaceDir, expandedPaths) {
+    const args = [];
+    for (const relPath of expandedPaths) {
+        args.push("-v", `${join(workspaceDir, SHADOWS_DIR, relPath)}:${CONTAINER_WORKSPACE}/${relPath}`);
+    }
+    return args;
+}
+// --- Helpers -----------------------------------------------------------------------------------------------------------------------------
+function createShadowEntry(sourcePath, shadowPath) {
+    if (existsSync(sourcePath) && !lstatSync(sourcePath).isDirectory()) {
+        mkdirSync(dirname(shadowPath), { recursive: true });
+        writeFileSync(shadowPath, "");
+    }
+    else {
+        mkdirSync(shadowPath, { recursive: true });
+    }
+}
+/**
+ * Walk the shadows/ tree and remove any entry whose relative path is not in the expected set.
+ * After removing leaf entries, prunes empty parent directories.
+ */
+function removeStaleEntries(baseDir, currentDir, expected) {
+    if (!existsSync(currentDir))
+        return;
+    for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
+        const fullPath = join(currentDir, entry.name);
+        const rel = relative(baseDir, fullPath);
+        if (expected.has(rel)) {
+            // This path is expected - keep it
+            continue;
+        }
+        if (entry.isDirectory()) {
+            // Check if any expected path is nested under this directory
+            const hasExpectedChild = [...expected].some((p) => isDescendantOf(p, rel));
+            if (hasExpectedChild) {
+                // Recurse into the directory to clean stale children
+                removeStaleEntries(baseDir, fullPath, expected);
+            }
+            else {
+                // No expected paths under here - remove entirely
+                safeRmSync(fullPath, { recursive: true, force: true });
+            }
+        }
+        else {
+            // Stale file - remove
+            safeRmSync(fullPath, { force: true });
+        }
+    }
+    // Prune if this directory is now empty (and is not the shadows root)
+    if (currentDir !== baseDir && readdirSync(currentDir).length === 0) {
+        safeRmSync(currentDir, { recursive: true, force: true });
+    }
+}
+/**
+ * Drop paths that descend from another path in the input (keeps only the outermost path per subtree),
+ * so nested matches (e.g. node_modules inside a shadowed .next dir) don't become redundant bind mounts.
+ */
+function removeNestedPaths(paths) {
+    const unique = [...new Set(paths)];
+    return unique.filter((p) => !unique.some((a) => a !== p && isDescendantOf(p, a)));
+}
+// Expects forward-slash paths (fast-glob output and shadows/ relative paths on POSIX).
+function isDescendantOf(child, ancestor) {
+    return child.startsWith(`${ancestor}/`);
+}

package/dist/lib/webterm.js

@@ -0,0 +1,305 @@
+// =========================================================================================================================================
+// src/lib/webterm.ts - Host-side logic for the web agent interface (webterm)
+// Sticky per-workspace host-port assignment from the global web_range, plus the container hooks that start
+// the baked webterm server once per container start and ask it what it is running.
+// =========================================================================================================================================
+import { spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { AGENTS_DIR, CONTAINER_USER, CONTAINER_WEBPANE_DIR, CONTAINER_WEBTERM_STATE_DIR, DEFAULT_WEB_AGENT, WEB_AGENTS, WEB_KEY_FILE_PATH, WEBPANE_DIR, WEBTERM_AGENT_FILE, WEBTERM_STATE_DIR, } from "./constants.js";
+import { canBind, containerPublishedPorts, dockerPublishedPorts, PORT_LOOPBACK_HOST } from "./ports.js";
+import { listWorkspaceIds, readWebPort, writeWebPort } from "./workspace-identity.js";
+// --- Port assignment (pure over the .lock files) -----------------------------------------------------------------------------------------
+/** Every web port currently assigned to a workspace, optionally excluding one workspace's own assignment. */
+export function collectAssignedWebPorts(excludeWorkspaceId) {
+    const taken = new Set();
+    for (const id of listWorkspaceIds()) {
+        if (id === excludeWorkspaceId)
+            continue;
+        const port = readWebPort(id);
+        if (port !== null)
+            taken.add(port);
+    }
+    return taken;
+}
+/** Lowest port in the range not already taken, or null when the range is exhausted. */
+export function nextFreeWebPort(range, taken) {
+    for (let port = range.start; port <= range.end; port++) {
+        if (!taken.has(port))
+            return port;
+    }
+    return null;
+}
+/**
+ * Return a workspace's sticky web port, assigning the lowest free port in the range when it has none.
+ * An already-assigned port is returned as-is even when it falls outside the range - stickiness wins;
+ * out-of-range ports move only when the user changes the range (reassignOutOfRangeWebPorts).
+ * This is pure over the .lock files: it never probes the host, so it can say a port is assigned but not
+ * that it can be published. resolveWebPort adds that.
+ */
+export function ensureWebPort(workspaceId, range) {
+    const existing = readWebPort(workspaceId);
+    if (existing !== null)
+        return { ok: true, port: existing };
+    const port = nextFreeWebPort(range, collectAssignedWebPorts(workspaceId));
+    if (port === null)
+        return { ok: false, reason: "exhausted" };
+    // A port that could not be recorded must not be used: it would be invisible to the next
+    // workspace's scan and handed out twice.
+    if (!writeWebPort(workspaceId, port))
+        return { ok: false, reason: "unrecorded" };
+    return { ok: true, port };
+}
+/**
+ * The host port this workspace's web interface should publish this session.
+ *
+ * `usable(port)` is the caller's test for "can this port carry the interface right now" - it covers both
+ * the host-side probe and any host port the workspace already declares in chamba.yaml. When the sticky
+ * assignment fails that test the port MOVES and the new one is persisted: sticky means it stays where it
+ * was last put, not that it stays somewhere unusable and warns about the same conflict at every start.
+ * When nothing in the range qualifies the old assignment is left alone rather than cleared, so the
+ * workspace keeps its identity and picks the port back up once the conflict clears.
+ */
+export async function resolveWebPort(workspaceId, range, usable) {
+    const assigned = ensureWebPort(workspaceId, range);
+    if (!assigned.ok)
+        return { ok: false, reason: assigned.reason, keptPort: readWebPort(workspaceId) };
+    if (await usable(assigned.port))
+        return { ok: true, port: assigned.port };
+    const taken = collectAssignedWebPorts(workspaceId);
+    for (let port = range.start; port <= range.end; port++) {
+        if (port === assigned.port || taken.has(port))
+            continue;
+        if (!(await usable(port)))
+            continue;
+        // Same rule as the first assignment: a port that could not be recorded must not be handed out.
+        if (!writeWebPort(workspaceId, port))
+            return { ok: false, reason: "unrecorded", keptPort: assigned.port };
+        return { ok: true, port, movedFrom: assigned.port };
+    }
+    return { ok: false, reason: "exhausted", keptPort: assigned.port };
+}
+/**
+ * Range-change walk: move only the sticky ports that fall outside the new range to the lowest free
+ * in-range port. In-range assignments are never touched. Returns the moves that were made.
+ */
+export function reassignOutOfRangeWebPorts(range) {
+    const moves = [];
+    for (const workspaceId of listWorkspaceIds()) {
+        const current = readWebPort(workspaceId);
+        if (current === null || (current >= range.start && current <= range.end))
+            continue;
+        const port = nextFreeWebPort(range, collectAssignedWebPorts(workspaceId));
+        if (port === null)
+            continue; // Range exhausted; leave the old assignment rather than dropping it.
+        if (!writeWebPort(workspaceId, port))
+            continue; // Not recorded - keep the old port rather than report a move that did not happen.
+        moves.push({ workspaceId, from: current, to: port });
+    }
+    return moves;
+}
+// --- Default agent (per workspace, kept on the host side of a mount) ---------------------------------------------------------------------
+/** This workspace's webterm state dir on the host - the directory the container sees as its state mount. */
+export function webtermStateDir(cacheDir) {
+    return join(cacheDir, WEBTERM_STATE_DIR);
+}
+/**
+ * The `docker run -v` args for the webterm state dir, creating it on the host first (docker would otherwise
+ * create it as root). Small on purpose: the only thing in it is the agent file the server writes.
+ */
+export function buildWebtermStateMountArgs(cacheDir) {
+    const host = webtermStateDir(cacheDir);
+    mkdirSync(host, { recursive: true });
+    return ["-v", `${host}:${CONTAINER_WEBTERM_STATE_DIR}`];
+}
+/**
+ * This workspace's web pane artifacts dir on the host: one directory per conversation, each holding that
+ * conversation's published pages and the feedback submitted on them. Under `agents/` on purpose - the pages
+ * are the agent's own output, and clearing agent memory is what clears them.
+ */
+export function webpaneDir(cacheDir) {
+    return join(cacheDir, AGENTS_DIR, WEBPANE_DIR);
+}
+/**
+ * The `docker run -v` args for the web pane artifacts dir, creating it on the host first (docker would
+ * otherwise create it as root). Mounted rather than kept in the container so a published page outlives the
+ * container it was written in, which is what lets a resumed conversation open its own pages again.
+ */
+export function buildWebpaneMountArgs(cacheDir) {
+    const host = webpaneDir(cacheDir);
+    mkdirSync(host, { recursive: true });
+    return ["-v", `${host}:${CONTAINER_WEBPANE_DIR}`];
+}
+/**
+ * Which agent this workspace's web sessions start with. The server writes the file whenever `webterm <agent>`
+ * moves the default, and it sits in the mounted state dir rather than the container's /tmp, so the choice
+ * outlives a container recreate. Falls back to the default agent when nothing has been chosen yet, and when
+ * the file holds something this chamba does not run - a value from a newer version, or a stray edit.
+ * It is also the agent the resume marker is written for, so a wrong answer here would resume nothing.
+ */
+export function readWebAgent(cacheDir) {
+    let value;
+    try {
+        value = readFileSync(join(webtermStateDir(cacheDir), WEBTERM_AGENT_FILE), "utf8").trim();
+    }
+    catch {
+        return DEFAULT_WEB_AGENT; // Never chosen, or the dir is not there yet.
+    }
+    return WEB_AGENTS.includes(value) ? value : DEFAULT_WEB_AGENT;
+}
+// --- Host-port and live-session probing ---------------------------------------------------------------------------------------------------
+/**
+ * True when this workspace can publish its sticky web port right now: either the port is free on the
+ * host, or this workspace's own running container is the one already publishing it (the normal case on
+ * the connect path). Anything else holding it - another container, an unrelated host process - means
+ * the mapping has to be dropped for this session, because chamba's own port mapping must never fail a
+ * session the way a chamba.yaml port does.
+ */
+export async function webPortUsable(webPort, containerName) {
+    if (containerPublishedPorts(containerName).has(webPort))
+        return true;
+    return !dockerPublishedPorts().has(webPort) && (await canBind(webPort));
+}
+/**
+ * The key this container's web interface is currently demanding, read from the file its server publishes
+ * before binding the port. A new key is minted at every server start and nothing on the host stores one,
+ * so it is always read fresh, right before it is used.
+ * Returns null when there is nothing to read: no container, no interface running, or a container built
+ * before the key existed. Callers then probe without a key, which is exactly what such an older server
+ * (which ignores the query parameter) expects.
+ */
+export function readWebKey(containerName) {
+    const result = spawnSync("docker", ["exec", "-u", CONTAINER_USER, containerName, "cat", WEB_KEY_FILE_PATH], { stdio: "pipe" });
+    if (result.status !== 0)
+        return null;
+    const key = result.stdout?.toString().trim();
+    return key ? key : null;
+}
+// The shape the server mints: 16 random bytes, hex. The key file is writable by every process in the
+// container, so anything read back from it is checked against this before the host builds a URL out of it
+// and hands that URL to a program. Argv-style spawning already keeps a strange value from being a command;
+// this keeps it from being a URL at all.
+const WEB_KEY_PATTERN = /^[0-9a-f]{32}$/;
+/** Whether a key read back from the container has the shape the server mints. */
+export function isWebKey(key) {
+    return key !== null && WEB_KEY_PATTERN.test(key);
+}
+/**
+ * The URL that opens this workspace's interface. The key is what the server demands of every caller, so a
+ * URL without one lands on a 403 - callers pass the key whenever they have a valid one, and the keyless
+ * form is only for showing a person where the interface lives.
+ */
+export function webInterfaceUrl(webPort, key) {
+    const base = `http://${PORT_LOOPBACK_HOST}:${webPort}`;
+    return isWebKey(key) ? `${base}/?k=${key}` : base;
+}
+/**
+ * Ask this workspace's web interface what it is running, over the published loopback port. `sessions` is
+ * how many agents are alive in the container - they outlive every browser connection and only end with
+ * the container - and `attached` how many of them a browser window is watching right now.
+ * `key` is what the interface demands of every caller (readWebKey); a wrong or missing one is answered
+ * with 403, which reads here like any other non-answer.
+ * Returns null when the interface did not answer at all, so callers can tell "running, nothing open"
+ * from "not running": the connect path relaunches the server on null, and the stop prompt warns only
+ * when sessions would be lost.
+ */
+export async function webSessionInfo(webPort, key) {
+    const query = key === null ? "" : `?k=${encodeURIComponent(key)}`;
+    try {
+        const response = await fetch(`http://${PORT_LOOPBACK_HOST}:${webPort}/status${query}`, {
+            signal: AbortSignal.timeout(WEB_STATUS_TIMEOUT_MS),
+        });
+        if (!response.ok)
+            return null;
+        const body = (await response.json());
+        if (typeof body.sessions !== "number" || typeof body.attached !== "number")
+            return null;
+        return { sessions: body.sessions, attached: body.attached };
+    }
+    catch {
+        return null; // Not listening, wrong thing listening, or too slow to matter.
+    }
+}
+/**
+ * Point an already-running interface at the directory this session was started from, so its new sessions open
+ * where a terminal session would. The interface takes that directory from the launcher, which only runs once
+ * per container start - so on a container that has been up since yesterday the default is yesterday's
+ * directory, and this is what moves it.
+ * `key` is what the interface demands of every caller (readWebKey); without one it answers 403, which reads
+ * here like any other refusal. Best-effort: a false only means the browser's "+ New session" still opens
+ * where it did, and the picker can be used instead.
+ */
+export async function setWebDefaultCwd(webPort, key, workdir) {
+    const query = key === null ? "" : `?k=${encodeURIComponent(key)}`;
+    try {
+        const response = await fetch(`http://${PORT_LOOPBACK_HOST}:${webPort}/cwd${query}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ cwd: workdir }),
+            signal: AbortSignal.timeout(WEB_STATUS_TIMEOUT_MS),
+        });
+        return response.ok;
+    }
+    catch {
+        return false; // Not listening, an interface too old to know the route, or too slow to matter.
+    }
+}
+// The interface is on loopback in the same machine, so a slow answer means something is wrong, not far.
+const WEB_STATUS_TIMEOUT_MS = 1500;
+/**
+ * Whether the interface is serving at all. Any HTTP answer counts, including the 403 a keyless probe gets:
+ * refusing a caller without a key is still proof that the server is up. Used where only liveness matters
+ * (did the launch work, is the interface still there), so those paths need no key and no docker exec.
+ */
+export async function webInterfaceAnswers(webPort) {
+    try {
+        await fetch(`http://${PORT_LOOPBACK_HOST}:${webPort}/status`, { signal: AbortSignal.timeout(WEB_STATUS_TIMEOUT_MS) });
+        return true;
+    }
+    catch {
+        return false; // Not listening, or too slow to matter.
+    }
+}
+// --- Container hooks (docker I/O, best-effort) --------------------------------------------------------------------------------------------
+/**
+ * The `docker exec` argv that starts the baked webterm server, with the given agent as the one its new
+ * sessions start with, opening them in `workdir`. The server runs every agent it knows, one per session, so
+ * this is a default rather than the only agent it will run. It is always passed explicitly - `webterm` on its
+ * own only prints usage.
+ *
+ * The directory travels as an env var rather than as `docker exec -w`: `-w` on a path docker cannot use
+ * fails the whole exec, which would cost the user the interface over something the server itself can just
+ * refuse and fall back to the workspace root.
+ */
+export function webtermExecArgs(containerName, agent, workdir) {
+    return ["exec", "-d", "-u", CONTAINER_USER, "-e", `WEBTERM_CWD=${workdir}`, containerName, "webterm", agent];
+}
+/**
+ * Start the baked webterm server detached, once per container start, defaulting to the given agent.
+ * The launcher is idempotent (exits quietly when the port is already bound).
+ * Best-effort - the user can always run `webterm <agent>` by hand.
+ */
+function startWebtermDetached(containerName, agent, workdir) {
+    spawnSync("docker", webtermExecArgs(containerName, agent, workdir), { stdio: "pipe" });
+}
+// How long to wait for a just-launched interface to answer, and how often to ask. `docker exec -d` returns
+// as soon as the process is detached, so these cover node starting up and binding the port.
+const WEB_START_TIMEOUT_MS = 8000;
+const WEB_START_POLL_MS = 250;
+/**
+ * Start the interface and wait until it actually answers on its port. `docker exec -d` reports success the
+ * moment the process detaches, which says nothing about whether the server came up, so without this a
+ * crashed launch would leave the greeting advertising a URL that never responds. Returns false when the
+ * interface never answered - the caller reports that and starts nothing in its place, leaving the user to
+ * retry `webterm <agent>` or run the agent in the terminal.
+ */
+export async function startWebtermAndVerify(containerName, agent, webPort, workdir) {
+    startWebtermDetached(containerName, agent, workdir);
+    const deadline = Date.now() + WEB_START_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        if (await webInterfaceAnswers(webPort))
+            return true;
+        await new Promise((r) => setTimeout(r, WEB_START_POLL_MS));
+    }
+    return false;
+}