@rryando/arcs 5.1.0 → 5.2.1

package/scripts/deploy-pi-bundle.mjs

@@ -0,0 +1,468 @@
+#!/usr/bin/env node
+
+// Deploy pi ARCS bundle from repo to pi config.
+//
+// Direction: repo → config ONLY. Never writes config → repo.
+//
+// What gets deployed:
+//   1. Sub-agent prompts → <destination>/agent/agents/<stem>.md   (global)
+//                          <destination>/.pi/agents/<stem>.md     (project)
+//   2. Skills tree       → <destination>/agent/skills/arcs-<name>/...  (global)
+//                          <destination>/.pi/skills/arcs-<name>/...    (project)
+//
+// The compiled agent format targets the pi subagents extension
+// (@tintinweb/pi-subagents) custom agent types: a Claude Code-shaped
+// .md with YAML frontmatter in pi's agent directory. pi's main session is
+// the orchestrator, so there is no settings.json default-agent merge —
+// every agent (including the arcs-* primary prompts) deploys as a spawnable
+// subagent type via the `Agent` tool / `@type` mentions.
+//
+// Frontmatter mapping (ARCS manifest → pi agent type):
+//   - `model: inherit` is OMITTED — "inherit parent" is the extension default.
+//     A pinned DEPLOY_MODEL_* value emits `model: <value>` instead.
+//   - permissions → `tools:` allowlist: edit→write/edit, bash→bash,
+//     mcp→ext:mcp, base read-only set read/grep/find/ls. Read-only
+//     specialists (code-reviewer, tech-architect, graph-explorer) get no
+//     mutation tools.
+//   - `task: allow` (primaries only) → `allowed_subagents: all`, mirroring
+//     the Task tool those prompts were written against.
+//
+// Env vars:
+//   DEPLOY_BUNDLE_ROOT  — override bundle root (default: opencode/arcs)
+//   DEPLOY_CONFIG_ROOT  — override config root (default: ~/.pi)
+//   DEPLOY_PROJECT_ROOT — override project root (default: repository root)
+//   DEPLOY_SCOPE        — `global` or `project` (default: `global`)
+//   DEPLOY_DRY_RUN      — "false" to actually write; anything else = dry-run (default: dry-run)
+//   DEPLOY_MODEL_HEAVY/STANDARD/LIGHT — 3-tier model overrides (default: "inherit")
+//
+// Outputs JSON to stdout: DeployResult. Exit code 0 on success, 1 on error.
+// codegraph/rtk are never wired: neither tool supports a pi install target.
+
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  isActiveAgentForMode,
+  isRetiredAgentForMode,
+  validateRetirementReplacements,
+} from "./lib/bundle-helpers.mjs";
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(scriptDir, "..");
+const defaultBundleRoot = resolve(repoRoot, "opencode/arcs");
+const defaultConfigRoot = resolve(homedir(), ".pi");
+const defaultProjectRoot = repoRoot;
+
+const bundleRoot = process.env.DEPLOY_BUNDLE_ROOT
+  ? resolve(repoRoot, process.env.DEPLOY_BUNDLE_ROOT)
+  : defaultBundleRoot;
+
+let configRoot;
+if (process.env.DEPLOY_CONFIG_ROOT) {
+  const rawPath = process.env.DEPLOY_CONFIG_ROOT;
+  if (rawPath.startsWith("~/")) {
+    configRoot = resolve(homedir(), rawPath.slice(2));
+  } else if (rawPath === "~") {
+    configRoot = homedir();
+  } else {
+    configRoot = resolve(homedir(), rawPath);
+  }
+} else {
+  configRoot = defaultConfigRoot;
+}
+
+const projectRoot = process.env.DEPLOY_PROJECT_ROOT
+  ? resolve(repoRoot, process.env.DEPLOY_PROJECT_ROOT)
+  : defaultProjectRoot;
+
+const scope = process.env.DEPLOY_SCOPE === "project" ? "project" : "global";
+const dryRun = process.env.DEPLOY_DRY_RUN !== "false";
+
+// Project deploys write into the project's own pi config dir; global deploys
+// write into ~/.pi (agents/skills land under agent/, the pi agent dir).
+const destination = scope === "project" ? resolve(projectRoot, ".pi") : configRoot;
+
+const SKILL_PREFIX = "arcs-";
+
+function isPromptPath(value) {
+  if (typeof value !== "string" || value.includes("\\")) return false;
+  const segments = value.split("/");
+  return (
+    segments.length >= 2 &&
+    segments[0] === "prompts" &&
+    segments.slice(1).every((segment) => segment !== "" && segment !== "." && segment !== "..") &&
+    segments.at(-1).endsWith(".txt")
+  );
+}
+
+function resolveBundlePromptPath(value) {
+  if (!isPromptPath(value)) throw new Error(`Invalid bundle prompt path: ${value}`);
+  const promptsRoot = resolve(bundleRoot, "prompts");
+  const resolvedPath = resolve(promptsRoot, ...value.split("/").slice(1));
+  const relativePath = relative(promptsRoot, resolvedPath);
+  if (relativePath.split(/[\\/]/).includes("..")) {
+    throw new Error(`Bundle prompt path escapes prompts/: ${value}`);
+  }
+  return resolvedPath;
+}
+
+// ---------------------------------------------------------------------------
+// Model tier configuration
+// ---------------------------------------------------------------------------
+// Env vars: DEPLOY_MODEL_HEAVY, DEPLOY_MODEL_STANDARD, DEPLOY_MODEL_LIGHT.
+// "inherit" (the default) means the agent inherits the parent pi session's
+// model — the extension default — so no `model:` frontmatter is emitted.
+const tierModels = {
+  heavy: process.env.DEPLOY_MODEL_HEAVY || "inherit",
+  standard: process.env.DEPLOY_MODEL_STANDARD || "inherit",
+  light: process.env.DEPLOY_MODEL_LIGHT || "inherit",
+};
+
+function readAgentRegistry() {
+  const manifestPath = resolve(bundleRoot, "manifest.json");
+  if (!existsSync(manifestPath)) throw new Error(`Agent registry not found at ${manifestPath}`);
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+  if (!Array.isArray(manifest.agents))
+    throw new Error("Invalid agent registry: agents must be an array");
+
+  const ids = new Set();
+  const sources = new Set();
+  const destinations = new Set();
+  for (const agent of manifest.agents) {
+    const valid =
+      agent &&
+      typeof agent.id === "string" &&
+      /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(agent.id) &&
+      ["active", "retired"].includes(agent.status) &&
+      ["primary", "subagent"].includes(agent.kind) &&
+      ["heavy", "standard", "light"].includes(agent.tier) &&
+      Array.isArray(agent.modes) &&
+      agent.modes.length > 0 &&
+      agent.modes.every((mode) => ["opencode", "claudecode", "pi"].includes(mode)) &&
+      isPromptPath(agent.source) &&
+      isPromptPath(agent.destination) &&
+      typeof agent.description === "string" &&
+      agent.description.length > 0 &&
+      agent.permissions &&
+      ["allow", "deny"].includes(agent.permissions.edit) &&
+      ["allow", "deny"].includes(agent.permissions.bash) &&
+      ["allow", "deny"].includes(agent.permissions.webfetch) &&
+      ["allow", "deny"].includes(agent.permissions.mcp) &&
+      ["allow", "deny"].includes(agent.permissions.task);
+    if (!valid) throw new Error(`Invalid agent registry record: ${JSON.stringify(agent)}`);
+    if (ids.has(agent.id)) throw new Error(`Duplicate agent registry id: ${agent.id}`);
+    if (sources.has(agent.source))
+      throw new Error(`Duplicate agent registry source: ${agent.source}`);
+    if (destinations.has(agent.destination))
+      throw new Error(`Duplicate agent registry destination: ${agent.destination}`);
+    ids.add(agent.id);
+    sources.add(agent.source);
+    destinations.add(agent.destination);
+  }
+  validateRetirementReplacements(manifest.agents);
+  return manifest.agents;
+}
+
+// ---------------------------------------------------------------------------
+// pi destination layout
+// ---------------------------------------------------------------------------
+
+function agentConfigRelative(stem) {
+  return scope === "project" ? `agents/${stem}.md` : `agent/agents/${stem}.md`;
+}
+
+function skillConfigRelative(skillName, rel) {
+  const skillsRoot = scope === "project" ? "skills" : "agent/skills";
+  return `${skillsRoot}/${SKILL_PREFIX}${skillName}/${rel}`;
+}
+
+function manifestConfigRelative() {
+  return ".arcs-bundle.json";
+}
+
+// ---------------------------------------------------------------------------
+// 1. Compile sub-agent prompts
+// ---------------------------------------------------------------------------
+
+function piTools(agent) {
+  const tools = ["read", "grep", "find", "ls"];
+  if (agent.permissions.edit === "allow") tools.push("write", "edit");
+  if (agent.permissions.bash === "allow") tools.push("bash");
+  if (agent.permissions.mcp === "allow") tools.push("ext:mcp");
+  return tools.join(", ");
+}
+
+function buildAgentSources() {
+  const promptsDir = resolve(bundleRoot, "prompts");
+  if (!existsSync(promptsDir)) {
+    throw new Error(`Prompts directory not found at ${promptsDir}`);
+  }
+
+  const registry = readAgentRegistry();
+  const registeredSources = new Set(registry.map((agent) => agent.source));
+  const promptFiles = readdirSync(promptsDir).filter((file) => file.endsWith(".txt"));
+  for (const file of promptFiles) {
+    const source = `prompts/${file}`;
+    if (!registeredSources.has(source)) throw new Error(`Unregistered prompt file: ${source}`);
+  }
+
+  const sources = [];
+
+  for (const agent of registry.filter((record) => isActiveAgentForMode(record, "pi"))) {
+    const stem = agent.id;
+    const sourcePath = resolveBundlePromptPath(agent.source);
+    if (!existsSync(sourcePath))
+      throw new Error(`Registered agent prompt not found: ${agent.source}`);
+    const promptContent = readFileSync(sourcePath, "utf-8");
+    const model = tierModels[agent.tier];
+
+    const frontmatter = ["---", `name: ${stem}`, `description: ${agent.description}`];
+
+    // "inherit" is the extension default — omit it so the agent inherits the
+    // parent session's model (matches Claude Code `model: inherit`).
+    if (model !== "inherit") {
+      frontmatter.push(`model: ${model}`);
+    }
+
+    frontmatter.push(`tools: ${piTools(agent)}`);
+
+    // primaries were authored with a Task tool (task: allow); on pi that is
+    // ownership-scoped nested delegation.
+    if (agent.permissions.task === "allow") {
+      frontmatter.push("allowed_subagents: all");
+    }
+
+    const compiledContent = [...frontmatter, "---", "", promptContent].join("\n");
+
+    sources.push({
+      stem,
+      compiledContent,
+      configRelative: agentConfigRelative(stem),
+    });
+  }
+
+  return sources;
+}
+
+// ---------------------------------------------------------------------------
+// 2. Walk skills tree
+// ---------------------------------------------------------------------------
+
+function buildSkillSources() {
+  const skillsDir = resolve(bundleRoot, "skills");
+  if (!existsSync(skillsDir)) return { skillNames: [], files: [] };
+
+  const skillNames = readdirSync(skillsDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name);
+
+  const files = [];
+  for (const skillName of skillNames) {
+    const skillRoot = resolve(skillsDir, skillName);
+    for (const absPath of walkFiles(skillRoot)) {
+      const rel = relative(skillRoot, absPath).split(/[\\/]/).join("/");
+      files.push({
+        skillName,
+        absSource: absPath,
+        configRelative: skillConfigRelative(skillName, rel),
+      });
+    }
+  }
+
+  return { skillNames, files };
+}
+
+function walkFiles(dir) {
+  const out = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = resolve(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...walkFiles(full));
+    } else if (entry.isFile()) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+function sha256(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+function readInstalledManifest() {
+  const manifestPath = resolve(destination, manifestConfigRelative());
+  if (!existsSync(manifestPath)) return null;
+  try {
+    const value = JSON.parse(readFileSync(manifestPath, "utf-8"));
+    return value?.bundleId === "arcs-pi-bundle" ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function ensureParentDir(filePath) {
+  mkdirSync(dirname(filePath), { recursive: true });
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const registry = readAgentRegistry();
+  const previousManifest = readInstalledManifest();
+  const agentSources = buildAgentSources();
+  const skillSources = buildSkillSources();
+
+  // Pass 1: Classify add/change/unchanged for every planned write
+  const filesAdded = [];
+  const filesChanged = [];
+  const filesUnchanged = [];
+
+  for (const { compiledContent, configRelative } of agentSources) {
+    const abs = resolve(destination, configRelative);
+    if (!existsSync(abs)) {
+      filesAdded.push(configRelative);
+    } else if (readFileSync(abs, "utf-8") !== compiledContent) {
+      filesChanged.push(configRelative);
+    } else {
+      filesUnchanged.push(configRelative);
+    }
+  }
+
+  for (const { absSource, configRelative } of skillSources.files) {
+    const abs = resolve(destination, configRelative);
+    const sourceContent = readFileSync(absSource);
+    if (!existsSync(abs)) {
+      filesAdded.push(configRelative);
+    } else {
+      const existing = readFileSync(abs);
+      if (Buffer.compare(existing, sourceContent) !== 0) {
+        filesChanged.push(configRelative);
+      } else {
+        filesUnchanged.push(configRelative);
+      }
+    }
+  }
+
+  // Orphans
+  const filesRemoved = [];
+
+  // Skill orphans — only `arcs-*/` directories that aren't in current source.
+  // The prefix gives us a safe namespace; foreign user skills are never touched.
+  const skillsTargetDir = resolve(destination, scope === "project" ? "skills" : "agent/skills");
+  const activeSkillDirs = new Set(skillSources.skillNames.map((n) => `${SKILL_PREFIX}${n}`));
+  const orphanSkillDirs = [];
+  if (existsSync(skillsTargetDir)) {
+    for (const entry of readdirSync(skillsTargetDir, { withFileTypes: true })) {
+      if (entry.isDirectory() && entry.name.startsWith(SKILL_PREFIX)) {
+        if (!activeSkillDirs.has(entry.name)) {
+          orphanSkillDirs.push(entry.name);
+          filesRemoved.push(`${scope === "project" ? "skills" : "agent/skills"}/${entry.name}`);
+        }
+      }
+    }
+  }
+
+  const retiredById = new Map(
+    registry
+      .filter((agent) => isRetiredAgentForMode(agent, "pi"))
+      .map((agent) => [agent.id, agent]),
+  );
+  for (const ownership of previousManifest?.agents ?? []) {
+    const retired = retiredById.get(ownership.id);
+    if (!retired) continue;
+    const expectedDestination = agentConfigRelative(retired.id);
+    if (ownership.promptDestination !== expectedDestination) continue;
+    const installedPath = resolve(destination, ownership.promptDestination);
+    if (existsSync(installedPath) && sha256(readFileSync(installedPath)) === ownership.sourceHash) {
+      filesRemoved.push(ownership.promptDestination);
+    }
+  }
+
+  // Pass 2: Write if not dry-run
+  if (!dryRun) {
+    for (const { compiledContent, configRelative } of agentSources) {
+      const abs = resolve(destination, configRelative);
+      ensureParentDir(abs);
+      writeFileSync(abs, compiledContent, "utf-8");
+    }
+
+    for (const { absSource, configRelative } of skillSources.files) {
+      const abs = resolve(destination, configRelative);
+      ensureParentDir(abs);
+      writeFileSync(abs, readFileSync(absSource));
+    }
+
+    for (const fileToRemove of filesRemoved) {
+      const abs = resolve(destination, fileToRemove);
+      if (existsSync(abs)) {
+        // Could be a file (agent orphan) or directory (skill orphan)
+        const isDir = statSync(abs).isDirectory();
+        rmSync(abs, { recursive: isDir, force: true });
+      }
+    }
+
+    const installedManifestPath = resolve(destination, manifestConfigRelative());
+    ensureParentDir(installedManifestPath);
+    writeFileSync(
+      installedManifestPath,
+      `${JSON.stringify(
+        {
+          bundleId: "arcs-pi-bundle",
+          installMode: `pi-${scope}`,
+          sourceBundleVersion: "deploy-script",
+          sourceBundleHash: sha256(readFileSync(resolve(bundleRoot, "manifest.json"))),
+          installedAt: new Date().toISOString(),
+          tierModels,
+          ownedPaths: [],
+          agents: agentSources.map((agent) => ({
+            id: agent.stem,
+            promptDestination: agent.configRelative,
+            sourceHash: sha256(agent.compiledContent),
+          })),
+        },
+        null,
+        2,
+      )}\n`,
+      "utf-8",
+    );
+  }
+
+  // codegraph/rtk: neither exposes a pi install target, so nothing to wire.
+  const result = {
+    dryRun,
+    platform: "pi",
+    scope,
+    source: bundleRoot,
+    destination,
+    modelConfig: tierModels,
+    filesAdded,
+    filesChanged,
+    filesRemoved,
+    filesUnchanged,
+    orphanSkillDirs,
+    codegraphWired: false,
+    rtkWired: false,
+  };
+
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+try {
+  main();
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`${message}\n`);
+  process.exitCode = 1;
+}

package/scripts/lint-bundle.mjs

@@ -77,7 +77,7 @@ function isAgentRegistryRecord(agent) {
     ["heavy", "standard", "light"].includes(agent.tier) &&
     Array.isArray(agent.modes) &&
     agent.modes.length > 0 &&
-    agent.modes.every((mode) => ["opencode", "claudecode"].includes(mode)) &&
+    agent.modes.every((mode) => ["opencode", "claudecode", "pi"].includes(mode)) &&
     isPromptPath(agent.source) &&
     isPromptPath(agent.destination) &&
     typeof agent.description === "string" &&

package/dist/shared/session-vocabulary.d.ts

@@ -1,88 +0,0 @@
-/**
- * Session-state vocabulary — the ONE derivation both sides of the wire read.
- *
- * A session carries two state fields: `status`, persisted by the store, and
- * `phase`, derived per response and never persisted. The moment two call sites
- * pick between them independently the product starts disagreeing with itself —
- * a table badged `running` under an `active` chip, or a server refusing the
- * resume the client just offered. Everything user-facing and every server gate
- * goes through `sessionState()` here, so there is nothing to keep in sync.
- *
- * The predicates take the RECORD, never a pre-picked string, for the same
- * reason the badge component does: handing the badge a record protects badge
- * call sites only, and a counter or an affordance gate takes no badge prop.
- *
- * ---------------------------------------------------------------------------
- * THIS MODULE MUST HAVE ZERO IMPORTS. Do not add one — not a type-only import,
- * not a `import type { SessionMeta }` for the parameter shapes below.
- *
- * `web/` imports this file directly by relative path (there is no alias and no
- * third package). Its being a LEAF — not the directory it sits in — is the
- * entire guarantee that no server module graph is dragged into the client
- * bundle. One import of anything under `src/utils/` or `src/web-server/` and
- * the CLI's transitive graph starts resolving inside `vite build`.
- *
- * The corollary of that reach: this file is typechecked under BOTH tsconfigs,
- * and `web/tsconfig.json` sets `noUncheckedIndexedAccess` and
- * `verbatimModuleSyntax` where the root tsconfig sets neither. A root-legal
- * edit here can fail `npm --workspace @arcs/web run typecheck`. Run both.
- * ---------------------------------------------------------------------------
- */
-/**
- * The two fields a session's state is read from — all this module ever needs of
- * a record, so a store record, a reconciled server view and a wire-shaped
- * client record can all be filtered, gated and badged through one derivation.
- *
- * Typed as plain strings rather than the `SessionStatus`/`SessionPhase` literal
- * unions on purpose. Pinning those here would mean either an import (forbidden
- * above) or a third hand-written copy of the wire vocabulary that the server
- * store and `web/src/api/client.ts` already mirror deliberately. What is shared
- * across the boundary is the DERIVATION, not the wire types; every caller keeps
- * passing its own precisely-typed record, which is assignable to this.
- */
-export interface SessionStateSource {
-    status: string;
-    phase?: string;
-}
-/**
- * The state a session is in, as the UI states it everywhere and as the server
- * decides from: the derived phase — the only signal reflecting whether the
- * session is live right now — falling back to the record's own status for a
- * record that reached a decision site without one (the record echoed by
- * `POST /run` carries no phase, and neither does a pre-phase endpoint).
- *
- * This is the single derivation site. `status` is still readable on the row
- * (the status cell's tooltip), but nothing decides anything from it alone.
- */
-export declare function sessionState(session: SessionStateSource): string;
-/**
- * Is this a session a human could still reach — as the badge beside it reads?
- *
- * What the sessions header counts as "N live". Takes the record so the count is
- * computed from the same field the badge one row below renders, rather than
- * from whichever of the two a call site happened to reach for.
- *
- * This is the SAFE half of the pair: across the reachable pairs above, `status`
- * and `phase` never disagree about liveness. A record stored `active` whose
- * process is gone derives `idle`, and `idle` is live — the record is not over —
- * so the count is right read either way. That is a property of today's
- * derivation, not a guarantee; reading the record keeps the count correct if it
- * stops holding. `isSessionAttached` below is where the two genuinely disagree.
- */
-export declare function isSessionLive(session: SessionStateSource): boolean;
-/**
- * Is a process driving this session right now?
- *
- * The gate on affordances that need the session's runtime thread free — today
- * the composer's headless resume and the server route behind it, neither of
- * which can attach to a session a terminal is already driving. Reading the
- * persisted status here is wrong in BOTH directions, and both are reachable
- * pairs: a record stored `active` whose process is gone derives `idle` — no
- * fresh evidence of attachment — and would be refused the resume it is the
- * perfect candidate for (`active`/`idle`), while a live `running` session
- * stored `idle` would be offered one that cannot work (`idle`/`running`).
- * `idle` is the state the whole affordance turns on; it is never `ended`, which
- * only a terminal status produces.
- */
-export declare function isSessionAttached(session: SessionStateSource): boolean;
-//# sourceMappingURL=session-vocabulary.d.ts.map

package/dist/shared/session-vocabulary.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"session-vocabulary.d.ts","sourceRoot":"","sources":["../../src/shared/session-vocabulary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAEhE;AAwCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAElE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAEtE"}

package/dist/shared/session-vocabulary.js

@@ -1,114 +0,0 @@
-/**
- * Session-state vocabulary — the ONE derivation both sides of the wire read.
- *
- * A session carries two state fields: `status`, persisted by the store, and
- * `phase`, derived per response and never persisted. The moment two call sites
- * pick between them independently the product starts disagreeing with itself —
- * a table badged `running` under an `active` chip, or a server refusing the
- * resume the client just offered. Everything user-facing and every server gate
- * goes through `sessionState()` here, so there is nothing to keep in sync.
- *
- * The predicates take the RECORD, never a pre-picked string, for the same
- * reason the badge component does: handing the badge a record protects badge
- * call sites only, and a counter or an affordance gate takes no badge prop.
- *
- * ---------------------------------------------------------------------------
- * THIS MODULE MUST HAVE ZERO IMPORTS. Do not add one — not a type-only import,
- * not a `import type { SessionMeta }` for the parameter shapes below.
- *
- * `web/` imports this file directly by relative path (there is no alias and no
- * third package). Its being a LEAF — not the directory it sits in — is the
- * entire guarantee that no server module graph is dragged into the client
- * bundle. One import of anything under `src/utils/` or `src/web-server/` and
- * the CLI's transitive graph starts resolving inside `vite build`.
- *
- * The corollary of that reach: this file is typechecked under BOTH tsconfigs,
- * and `web/tsconfig.json` sets `noUncheckedIndexedAccess` and
- * `verbatimModuleSyntax` where the root tsconfig sets neither. A root-legal
- * edit here can fail `npm --workspace @arcs/web run typecheck`. Run both.
- * ---------------------------------------------------------------------------
- */
-/**
- * The state a session is in, as the UI states it everywhere and as the server
- * decides from: the derived phase — the only signal reflecting whether the
- * session is live right now — falling back to the record's own status for a
- * record that reached a decision site without one (the record echoed by
- * `POST /run` carries no phase, and neither does a pre-phase endpoint).
- *
- * This is the single derivation site. `status` is still readable on the row
- * (the status cell's tooltip), but nothing decides anything from it alone.
- */
-export function sessionState(session) {
-    return session.phase ?? session.status;
-}
-/** States meaning "this session is not over": the live phases, plus the raw
- *  `active`/`idle` a record that arrived without a phase is badged with. */
-const LIVE_STATES = new Set(["running", "idle", "active"]);
-/**
- * States meaning "a process is driving this session right now".
- *
- * Deliberately NARROWER than `LIVE_STATES`, and the reason both sets are
- * private to this module rather than living at their call sites: `idle` is live
- * — the record is not over and the session list counts it — but nothing holds
- * its runtime thread, which is exactly the session a headless resume works on.
- * One shared "live" set would silently conflate "not over" with "attached" and
- * take the resume affordance away from every session that can actually use it.
- *
- * REACHABLE PAIRS. The server's derivation (`deriveSessionPhase` →
- * `reconcilePhase` → `runDeadlinePhase`, all composed in `withPhases`) can only
- * ever produce these (`status`, `phase`) pairs, exhaustively:
- *
- *   active/idle · active/running · completed/ended · disconnected/ended ·
- *   failed/failed · idle/idle · idle/running
- *
- * So `ended` comes ONLY from a terminal status (`completed`/`disconnected`):
- * the derivation returns it before looking at any liveness evidence, the
- * reconciler early-returns on every non-`running` derivation, and both probes
- * can only demote `running` to `idle`. A record stored `active` whose process
- * is gone therefore derives `idle` — "no fresh evidence of attachment" — and
- * never `ended`. Both sit outside this set, so this predicate answers the same
- * either way; the pair that carries the meaning is `active`/`idle`, because
- * that is what "the process is gone" actually looks like on the wire.
- *
- * `active` itself is a persisted status, reachable only through
- * `sessionState`'s fallback for a record handed to a predicate without a
- * derived phase. Server call sites go through `withPhases` first, so the phase
- * decides in practice; the fallback is the conservative answer for anything
- * that does not — treat as attached and refuse, rather than silently accept.
- */
-const ATTACHED_STATES = new Set(["running", "active"]);
-/**
- * Is this a session a human could still reach — as the badge beside it reads?
- *
- * What the sessions header counts as "N live". Takes the record so the count is
- * computed from the same field the badge one row below renders, rather than
- * from whichever of the two a call site happened to reach for.
- *
- * This is the SAFE half of the pair: across the reachable pairs above, `status`
- * and `phase` never disagree about liveness. A record stored `active` whose
- * process is gone derives `idle`, and `idle` is live — the record is not over —
- * so the count is right read either way. That is a property of today's
- * derivation, not a guarantee; reading the record keeps the count correct if it
- * stops holding. `isSessionAttached` below is where the two genuinely disagree.
- */
-export function isSessionLive(session) {
-    return LIVE_STATES.has(sessionState(session));
-}
-/**
- * Is a process driving this session right now?
- *
- * The gate on affordances that need the session's runtime thread free — today
- * the composer's headless resume and the server route behind it, neither of
- * which can attach to a session a terminal is already driving. Reading the
- * persisted status here is wrong in BOTH directions, and both are reachable
- * pairs: a record stored `active` whose process is gone derives `idle` — no
- * fresh evidence of attachment — and would be refused the resume it is the
- * perfect candidate for (`active`/`idle`), while a live `running` session
- * stored `idle` would be offered one that cannot work (`idle`/`running`).
- * `idle` is the state the whole affordance turns on; it is never `ended`, which
- * only a terminal status produces.
- */
-export function isSessionAttached(session) {
-    return ATTACHED_STATES.has(sessionState(session));
-}
-//# sourceMappingURL=session-vocabulary.js.map