@agentprojectcontext/apx 1.81.0 → 1.89.1

package/src/interfaces/cli/commands/agent.js

@@ -1,11 +1,15 @@
 import fs from "node:fs";
-import path from "node:path";
-import { findApfRoot, readAgents, readVaultAgents, readVaultAgent, VAULT_DIR, SLUG_RE } from "#core/apc/parser.js";
+import { findApfRoot, readAgents, readVaultAgents, readVaultAgent, vaultAgentFile, VAULT_DIR, SLUG_RE } from "#core/apc/parser.js";
 import { apcAgentFile } from "#core/apc/paths.js";
 import { writeAgentFile, writeVaultAgentFile, removeVaultAgent, restoreVaultAgent, addImportedAgent, ensureAgentDir } from "#core/apc/scaffold.js";
 import { ensureAgentRuntimeDir, agentMemoryPath } from "#core/agent/memory.js";
+import {
+  AGENT_TYPE_VALUES, BLOB_KEYS, isBlobKey, normalizeAgentType, pickBlob,
+} from "#core/apc/agent-identity.js";
+import { readOrganization, resolveAreaSlug } from "#core/stores/organization.js";
 import { http } from "../http.js";
-import { resolveProjectId } from "./project.js";
+import { readStdinSync } from "../stdin.js";
+import { resolveProjectId, resolveProjectRoot } from "./project.js";
 
 // ── ANSI ──────────────────────────────────────────────────────────────────────
 const c = { reset:"\x1b[0m", bold:"\x1b[1m", dim:"\x1b[2m", cyan:"\x1b[36m", green:"\x1b[32m", yellow:"\x1b[33m", gray:"\x1b[90m" };
@@ -15,10 +19,81 @@ const cyan = (s) => `${c.cyan}${s}${c.reset}`;
 const gray = (s) => `${c.gray}${s}${c.reset}`;
 const tag  = (s) => `${c.yellow}${s}${c.reset}`;
 
-function requireRoot() {
-  const root = findApfRoot();
-  if (!root) throw new Error("not inside an APC project (run `apx init` first)");
-  return root;
+// The project these subcommands read and write: `--project <name|id|path>`
+// when given, otherwise the one cwd sits inside.
+function resolveRoot(args) {
+  return resolveProjectRoot(args?.flags?.project);
+}
+
+// For the two commands that only WANT a project if there is one (they fall back
+// to the vault). Honours --project, returns null instead of throwing.
+async function resolveRootOptional(args) {
+  if (args?.flags?.project) return resolveRoot(args);
+  return findApfRoot();
+}
+
+function flagValue(flags, ...names) {
+  for (const n of names) {
+    const v = flags?.[n];
+    if (v !== undefined && v !== true && v !== "") return String(v);
+  }
+  return null;
+}
+
+/**
+ * The agent's system prompt — everything after the frontmatter in
+ * `.apc/agents/<slug>.md`, injected by buildAgentSystem() as
+ * "# Custom instructions".
+ *
+ * WHY THIS EXISTS. `apx agent add` used to write frontmatter only: there was no
+ * flag for the body and `writeAgentFile`'s 4th argument was never passed. The
+ * command exited 0, so an agent created from the CLI (or by the super-agent,
+ * which follows the apx-agent skill) silently ran on three metadata fields with
+ * no instructions at all — while the daemon API and the web UI have always been
+ * able to write it via `system`. This closes that gap.
+ *
+ * Three ways in, because a system prompt is many lines and paragraphs:
+ *   --prompt "text"        inline, for one-liners
+ *   --prompt-file <path>   read from a file
+ *   --prompt -             read from stdin (heredoc / pipe) — the practical one
+ */
+function readPromptFlag(flags) {
+  const file = flagValue(flags, "prompt-file", "system-file");
+  if (file) {
+    if (!fs.existsSync(file)) throw new Error(`--prompt-file: no such file "${file}"`);
+    return fs.readFileSync(file, "utf8").trim();
+  }
+  const inline = flagValue(flags, "prompt", "system");
+  if (inline === "-") return readStdinSync().trim();
+  if (inline) return inline;
+  return null;
+}
+
+function readTypeFlag(flags) {
+  const raw = flagValue(flags, "type");
+  if (!raw) return null;
+  const type = normalizeAgentType(raw);
+  if (!type) {
+    throw new Error(`invalid --type "${raw}" — one of: ${AGENT_TYPE_VALUES.join(", ")}`);
+  }
+  return type;
+}
+
+/**
+ * The agent's avatar: a blob preset key. `--icon <key>` pins one, otherwise one
+ * is drawn from the presets this project isn't using yet — an agent with no
+ * `Icon` renders as a grey lettered disc in every surface, which is what every
+ * CLI- and MCP-created agent used to get.
+ */
+function resolveIconFlag(flags, roster) {
+  const raw = flagValue(flags, "icon", "avatar", "blob");
+  if (raw) {
+    if (!isBlobKey(raw)) {
+      throw new Error(`invalid --icon "${raw}" — one of: ${BLOB_KEYS.join(", ")}`);
+    }
+    return raw;
+  }
+  return pickBlob({ taken: roster.map((a) => a.fields?.Icon).filter(Boolean) });
 }
 
 async function nudgeDaemon(root) {
@@ -35,7 +110,7 @@ export async function cmdAgentAdd(args) {
   if (!slug) throw new Error("apx agent add: missing <slug>");
   if (!SLUG_RE.test(slug)) throw new Error(`invalid slug "${slug}"`);
 
-  const root = requireRoot();
+  const root = await resolveRoot(args);
   const existing = readAgents(root);
   if (existing.some((a) => a.slug === slug)) {
     throw new Error(`agent "${slug}" already exists`);
@@ -47,10 +122,34 @@ export async function cmdAgentAdd(args) {
   if (f.model && f.model !== true)      fields.Model = f.model;
   if (f.language && f.language !== true) fields.Language = f.language;
   if (f.description && f.description !== true) fields.Description = f.description;
+  if (f.area && f.area !== true) {
+    const area = resolveAreaSlug(String(f.area), readOrganization(root));
+    if (area) fields.Area = area;
+  }
+  if (f.parent && f.parent !== true)    fields.Parent = String(f.parent);
   if (f.skills && f.skills !== true)    fields.Skills = String(f.skills).split(",").map((s) => s.trim()).filter(Boolean);
-  if (f.tools && f.tools !== true)      fields.Tools = String(f.tools).split(",").map((s) => s.trim()).filter(Boolean);
 
-  writeAgentFile(root, slug, fields);
+  const type = readTypeFlag(f);
+  if (type) {
+    fields.Type = type;
+    // An orchestrator is a master; the daemon and the web already tie the two
+    // together on create, so the CLI can't be the one that disagrees.
+    if (type === "orchestrator") fields.Master = true;
+  }
+  // Every agent gets a face, same as the daemon API does. Drawn from the blobs
+  // this project isn't using yet so the team stays distinguishable.
+  fields.Icon = resolveIconFlag(f, existing);
+  // Omitted tools ⇒ leave the field UNDECLARED, matching the daemon API. A
+  // declared list is a deliberate narrowing that wins forever; writing one on
+  // create froze the agent to a snapshot of the catalog instead of letting it
+  // inherit the broad default.
+  if (f.tools && f.tools !== true) {
+    fields.Tools = String(f.tools).split(",").map((s) => s.trim()).filter(Boolean);
+  }
+
+  const prompt = readPromptFlag(f);
+
+  writeAgentFile(root, slug, fields, prompt || "");
   ensureAgentDir(root, slug);
   ensureAgentRuntimeDir(root, slug);
   await nudgeDaemon(root);
@@ -59,18 +158,117 @@ export async function cmdAgentAdd(args) {
   for (const [k, v] of Object.entries(fields)) {
     console.log(`  ${k}: ${Array.isArray(v) ? v.join(", ") : v}`);
   }
+  // Say it out loud either way. A prompt-less agent runs on its frontmatter
+  // alone, which is almost never what the author meant — and the old silence
+  // is exactly why that went unnoticed.
+  if (prompt) {
+    console.log(`  Prompt: ${Buffer.byteLength(prompt)} bytes`);
+  } else {
+    console.log(
+      `\n  ${tag("no system prompt")} — this agent has metadata but no instructions.` +
+      `\n  Add one with: apx agent set ${slug} --prompt - <<'EOF' … EOF`
+    );
+  }
+}
+
+// Edit an existing agent: merge frontmatter fields and/or replace the system
+// prompt. The CLI had no edit path at all, so an agent created without a prompt
+// could never get one without hand-editing the file (which the skill forbids,
+// since AGENTS.md has to be regenerated).
+export async function cmdAgentSet(args) {
+  const slug = args._[0];
+  if (!slug) throw new Error("apx agent set: missing <slug>");
+
+  const root = await resolveRoot(args);
+  const existing = readAgents(root).find((a) => a.slug === slug);
+  if (!existing) {
+    throw new Error(`agent "${slug}" not found — run \`apx agent list\` to see this project's agents`);
+  }
+  if (existing.source !== "local") {
+    throw new Error(
+      `agent "${slug}" comes from the ${existing.source} layer — run \`apx agent import ${slug} --copy\` first to get a local copy to edit`
+    );
+  }
+
+  const fields = { ...(existing.fields || {}) };
+  const f = args.flags;
+  const set = (key, flag) => {
+    const v = flagValue(f, flag);
+    if (v === null) return false;
+    fields[key] = v;
+    return true;
+  };
+  let touched = false;
+  for (const [key, flag] of [
+    ["Role", "role"], ["Model", "model"], ["Language", "language"],
+    ["Description", "description"], ["Emoji", "emoji"],
+    ["Parent", "parent"],
+  ]) {
+    if (set(key, flag)) touched = true;
+  }
+  for (const [key, flag] of [["Skills", "skills"], ["Tools", "tools"]]) {
+    const v = flagValue(f, flag);
+    if (v === null) continue;
+    fields[key] = v.split(",").map((s) => s.trim()).filter(Boolean);
+    touched = true;
+  }
+  const type = readTypeFlag(f);
+  if (type) {
+    fields.Type = type;
+    if (type === "orchestrator") fields.Master = true;
+    touched = true;
+  }
+  const icon = flagValue(f, "icon", "avatar", "blob");
+  if (icon) {
+    if (!isBlobKey(icon)) throw new Error(`invalid --icon "${icon}" — one of: ${BLOB_KEYS.join(", ")}`);
+    fields.Icon = icon;
+    touched = true;
+  }
+  const areaRaw = flagValue(f, "area");
+  if (areaRaw !== null) {
+    const area = resolveAreaSlug(areaRaw, readOrganization(root));
+    if (area) fields.Area = area;
+    else delete fields.Area;
+    touched = true;
+  }
+
+  const prompt = readPromptFlag(f);
+  if (prompt === null && !touched) {
+    throw new Error(
+      "apx agent set: nothing to change — pass --prompt/--prompt-file or a field flag (--role, --model, --description, …)"
+    );
+  }
+
+  // A field-only edit must not wipe the prompt the agent already had.
+  const body = prompt === null ? (existing.body || "") : prompt;
+  writeAgentFile(root, slug, fields, body);
+  ensureAgentDir(root, slug);
+  ensureAgentRuntimeDir(root, slug);
+  await nudgeDaemon(root);
+
+  console.log(`Updated agent ${slug}`);
+  for (const [k, v] of Object.entries(fields)) {
+    console.log(`  ${k}: ${Array.isArray(v) ? v.join(", ") : v}`);
+  }
+  if (prompt !== null) console.log(`  Prompt: ${Buffer.byteLength(body)} bytes`);
 }
 
-export function cmdAgentList() {
-  const root = requireRoot();
+export async function cmdAgentList(args) {
+  // --all: every agent across every registered project, with the project next to
+  // it. This is what makes cross-project addressing possible — when you want to
+  // message an agent (a2a) you need to know which project owns it, and two
+  // projects can each have a "rocky". Needs the daemon (project registry).
+  if (args?.flags?.all) return cmdAgentListAll();
+
+  const root = await resolveRoot(args);
   const agents = readAgents(root);
   if (agents.length === 0) {
-    console.log(dim("(no agents — try `apx agent add <slug>` or `apx agent import <slug>`)"));
+    console.log(dim("(no agents — try `apx agent add <slug>` or `apx agent import <slug>`, or `apx agent list --all` across projects)"));
     return;
   }
   console.log();
   for (const a of agents) {
-    const src   = a.source === "vault" ? tag(" ↑ vault") : a.source === "legacy" ? gray(" ↑ legacy") : "";
+    const src   = a.source === "vault" ? tag(" ↑ vault") : "";
     const role  = a.fields.Role  ? dim(a.fields.Role)  : gray("—");
     const model = a.fields.Model ? dim(a.fields.Model) : gray("—");
     console.log(`  ${bold(a.slug)}${src}  ${role}  ${cyan(model)}`);
@@ -78,10 +276,35 @@ export function cmdAgentList() {
   console.log();
 }
 
-export function cmdAgentGet(args) {
+// `apx agent list --all` — one line per (agent, project) across the whole
+// registry, plus the super-agent. The right-hand project column is the address
+// you pass to `apx send … --project <name>`.
+async function cmdAgentListAll() {
+  const projects = await http.get("/api/projects");
+  console.log();
+  console.log(`  ${bold("super-agent")}  ${gray("→")}  ${dim("default")}  ${gray("(reachable as the daemon fallback)")}`);
+  let total = 0;
+  for (const proj of projects) {
+    let agents = [];
+    try { agents = readAgents(proj.path); } catch { /* unreadable project */ }
+    if (agents.length === 0) continue;
+    console.log();
+    console.log(`  ${cyan(proj.name)} ${gray(`#${proj.id}`)}`);
+    for (const a of agents) {
+      const role = a.fields.Role ? dim(a.fields.Role) : gray("—");
+      console.log(`    ${bold(a.slug)}  ${role}`);
+      total++;
+    }
+  }
+  console.log();
+  console.log(dim(`  ${total} agent(s) across ${projects.length} project(s). Address one with: apx send <from> <slug> --project <name>`));
+  console.log();
+}
+
+export async function cmdAgentGet(args) {
   const slug = args._[0];
   if (!slug) throw new Error("apx agent get: missing <slug>");
-  const root = requireRoot();
+  const root = await resolveRoot(args);
   const a = readAgents(root).find((x) => x.slug === slug);
   if (!a) {
     // Check vault and suggest import
@@ -92,7 +315,7 @@ export function cmdAgentGet(args) {
     }
     throw new Error(`agent "${slug}" not found`);
   }
-  const src = a.source === "vault" ? tag(" ↑ vault") : a.source === "legacy" ? gray(" ↑ legacy") : "";
+  const src = a.source === "vault" ? tag(" ↑ vault") : "";
   console.log(`\n  ${bold(a.slug)}${src}`);
   for (const [k, v] of Object.entries(a.fields)) {
     console.log(`  ${gray(k.padEnd(12))}  ${Array.isArray(v) ? v.join(", ") : v}`);
@@ -106,7 +329,7 @@ export async function cmdAgentRemove(args) {
   if (!slug) throw new Error("apx agent remove: missing <slug> — usage: apx agent remove <slug>");
   // Resolve locally first so we can give a clear message + suggestions instead
   // of a bare 404 when the slug is wrong.
-  const root = findApfRoot();
+  const root = await resolveRootOptional(args);
   if (root) {
     const local = readAgents(root).find((a) => a.slug === slug);
     if (!local) {
@@ -150,7 +373,7 @@ export async function cmdAgentVaultAdd(args) {
   if (!slug || !SLUG_RE.test(slug)) throw new Error("apx agent vault add: missing or invalid <slug>");
 
   // If we're inside a project, offer to copy the local agent to vault
-  const root = findApfRoot();
+  const root = await resolveRootOptional(args);
   if (root) {
     const local = readAgents(root).find((a) => a.slug === slug && a.source === "local");
     if (local) {
@@ -206,10 +429,12 @@ export function cmdAgentVaultRestore(args) {
 export async function cmdAgentImport(args) {
   const slug = args._[0];
   if (!slug) throw new Error("apx agent import: missing <slug>");
-  const root = requireRoot();
+  const root = await resolveRoot(args);
 
-  const vaultPath = path.join(VAULT_DIR, `${slug}.md`);
-  if (!fs.existsSync(vaultPath)) {
+  // Layered lookup (user file → bundled default) — see vaultAgentFile. Reading
+  // the user layer alone made every bundled agent unimportable.
+  const vaultPath = vaultAgentFile(slug);
+  if (!vaultPath) {
     const vault = readVaultAgents();
     const available = vault.map((a) => a.slug).join(", ") || "(none)";
     throw new Error(`"${slug}" not found in vault. Available: ${available}`);

package/src/interfaces/cli/commands/code.js

@@ -1,6 +1,6 @@
 // `apx code` — launch the APX terminal coding assistant (Solid.js TUI).
 // The TUI runs its TypeScript source directly under bun; there is no
-// legacy readline fallback anymore (removed with the old sys.js chat).
+// readline fallback anymore (it went with the old sys.js chat).
 import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, resolve } from "node:path";

package/src/interfaces/cli/commands/commitment.js

@@ -7,6 +7,7 @@
 //   apx commitment show <id>   [--project X]
 //   apx commitment kept <id>   [--project X] [--note "..."]
 //   apx commitment missed <id> [--project X] [--note "..."]
+//   apx commitment drop <id>   [--project X] [--note "..."]   filed by mistake
 //   apx commitment renegotiate <id> --due <ISO> [--project X] [--note "..."]
 //
 // A task is something to do; a commitment is something you promised a person.
@@ -20,6 +21,7 @@ export const COMMITMENT_USAGE = {
   show:        "apx commitment show <id> [--project X]",
   kept:        'apx commitment kept <id> [--project X] [--note "..."]',
   missed:      'apx commitment missed <id> [--project X] [--note "..."]',
+  drop:        'apx commitment drop <id> [--project X] [--note "..."]',
   renegotiate: 'apx commitment renegotiate <id> --due <ISO> [--project X] [--note "..."]',
 };
 
@@ -139,6 +141,9 @@ async function close(args, sub) {
 
 export const cmdCommitmentKept = (args) => close(args, "kept");
 export const cmdCommitmentMissed = (args) => close(args, "missed");
+// Not an alias of `missed`: nobody was waiting on a promise filed by mistake,
+// so it must not land in the broken-promise count.
+export const cmdCommitmentDrop = (args) => close(args, "drop");
 
 export async function cmdCommitmentRenegotiate(args) {
   const id = args?._?.[0];

package/src/interfaces/cli/commands/config.js

@@ -1,6 +1,21 @@
+// `apx config` — read and edit configuration at either layer.
+//
+// APX has two config layers and this command reaches both:
+//   default            the PROJECT layer, `.apc/config.json` (committed)
+//   --global           the GLOBAL layer, `~/.apx/config.json` (machine-local)
+//
+// The global branch goes through the daemon's `/api/admin/config` route rather
+// than calling writeConfig() here. That route writes the file AND hot-reloads
+// the daemon's in-memory copy, re-registers log masking for any secret just
+// stored, and refreshes the scheduler/plugin views. Writing the file directly
+// would leave every one of those stale until the next restart.
+//
+// Scope vocabulary matches `apx obsidian` (project|global), not the MCP one
+// (shared|runtime|global) — see the scope row in AGENTS.md's glossary.
 import { http } from "../http.js";
 import { resolveProjectId } from "./project.js";
-import { readConfig, writeConfig } from "#core/config/index.js";
+import { readConfig, writeConfig, CONFIG_PATH } from "#core/config/index.js";
+import { isSecretKey } from "#core/config/redact.js";
 import { DEFAULT_PERMISSION_MODE } from "#core/constants/permissions.js";
 
 function parseValue(raw) {
@@ -13,7 +28,46 @@ function parseValue(raw) {
   }
 }
 
+// `--global` (boolean) or `--scope global|project`. Anything else is a typo
+// worth failing on rather than silently treating as project scope — writing a
+// global key like engines.*.api_key into a committed .apc/config.json is the
+// exact accident this flag exists to prevent.
+export function isGlobalScope(flags = {}) {
+  if (flags.global) return true;
+  if (flags.scope === undefined || flags.scope === null || flags.scope === "") return false;
+  const s = String(flags.scope).toLowerCase();
+  if (s === "global" || s === "default") return true;
+  if (s === "project") return false;
+  throw new Error(`unknown --scope "${flags.scope}" (use project|global)`);
+}
+
+// --effective and --only-overrides both name the project↔global merge, which
+// does not exist when the global file *is* the whole story.
+function rejectMergeFlags(flags, cmd) {
+  const bad = ["effective", "only-overrides"].filter((f) => flags[f]);
+  if (bad.length) {
+    throw new Error(
+      `apx ${cmd}: --${bad[0]} describes the project/global merge and does not apply to --global; ` +
+        `drop --global to inspect a project, or drop --${bad[0]} to print ${CONFIG_PATH}`
+    );
+  }
+}
+
+async function showGlobal(args) {
+  rejectMergeFlags(args.flags, "config show");
+  const { config } = await http.get("/api/admin/config");
+  // Header goes to stderr so `apx config show --global | jq .` still gets clean
+  // JSON on stdout. Secrets arrive redacted from the route — rule 3 forbids
+  // captured output carrying a real key.
+  process.stderr.write(
+    `# ${CONFIG_PATH} (global — secrets redacted)\n` +
+      `# project overrides: apx config show (inside a project)\n\n`
+  );
+  process.stdout.write(JSON.stringify(config, null, 2) + "\n");
+}
+
 export async function cmdConfigShow(args) {
+  if (isGlobalScope(args.flags)) return showGlobal(args);
   const pid = await resolveProjectId(args?.flags?.project);
   const data = await http.get(`/api/projects/${pid}/config`);
   if (args.flags.effective) {
@@ -41,20 +95,45 @@ export async function cmdConfigSet(args) {
   const key = args._[0];
   const valueRaw = args._.slice(1).join(" ");
   if (!key || !valueRaw) {
-    throw new Error('apx config set: usage: apx config set <key.path> <value>');
+    throw new Error('apx config set: usage: apx config set [--global] <key.path> <value>');
   }
-  const pid = await resolveProjectId(args?.flags?.project);
   const value = parseValue(valueRaw);
+  // Name the layer in the confirmation: the whole point of the flag is that
+  // "set" alone used to leave people guessing which file they just edited.
+  if (isGlobalScope(args.flags)) {
+    await http.patch("/api/admin/config", { set: { [key]: value } });
+    console.log(`set ${key} = ${JSON.stringify(value)} (global: ${CONFIG_PATH})`);
+    return;
+  }
+  // Warn, don't block: a project may legitimately override a non-secret key
+  // that trips the heuristic, and refusing would strand that case. But
+  // .apc/config.json is COMMITTED (rule 3), so a credential landing there is a
+  // leak the user needs to hear about before it reaches git — not after.
+  // Never echo the value itself into the warning.
+  if (isSecretKey(key)) {
+    process.stderr.write(
+      `apx: warning: "${key}" looks like a secret, and this writes the project's ` +
+        `.apc/config.json — which is committed to git.\n` +
+        `     Write it to ${CONFIG_PATH} instead:\n` +
+        `       apx config set --global ${key} <value>\n`
+    );
+  }
+  const pid = await resolveProjectId(args?.flags?.project);
   await http.patch(`/api/projects/${pid}/config`, { set: { [key]: value } });
-  console.log(`set ${key} = ${JSON.stringify(value)}`);
+  console.log(`set ${key} = ${JSON.stringify(value)} (project: .apc/config.json)`);
 }
 
 export async function cmdConfigUnset(args) {
   const key = args._[0];
-  if (!key) throw new Error("apx config unset: usage: apx config unset <key.path>");
+  if (!key) throw new Error("apx config unset: usage: apx config unset [--global] <key.path>");
+  if (isGlobalScope(args.flags)) {
+    await http.patch("/api/admin/config", { unset: [key] });
+    console.log(`unset ${key} (global: ${CONFIG_PATH})`);
+    return;
+  }
   const pid = await resolveProjectId(args?.flags?.project);
   await http.patch(`/api/projects/${pid}/config`, { unset: [key] });
-  console.log(`unset ${key}`);
+  console.log(`unset ${key} (project: .apc/config.json)`);
 }
 
 export function cmdPermission(args = {}) {

package/src/interfaces/cli/commands/exec.js

@@ -121,6 +121,19 @@ function labelForEvent(event) {
   }
 }
 
+// A session title has to be readable in a list of twenty, so it is the prompt's
+// opening words rather than "New session" — the panel's session list is the
+// only place a `--code` turn can be found again, and twelve rows all reading
+// "New session" is the same as not finding it.
+const TITLE_MAX = 60;
+export function codeSessionTitle(prompt) {
+  const flat = String(prompt || "").replace(/\s+/g, " ").trim();
+  if (!flat) return "Code";
+  const firstLine = flat.split(/(?<=[.?!])\s/)[0] || flat;
+  const base = firstLine.length <= TITLE_MAX ? firstLine : flat;
+  return base.length <= TITLE_MAX ? base : base.slice(0, TITLE_MAX - 1).trimEnd() + "…";
+}
+
 async function readPromptFromStdin() {
   const fs = await import("node:fs");
   if (process.stdin.isTTY) return "";
@@ -138,6 +151,72 @@ async function readPromptFromStdin() {
   return chunks.join("").trim();
 }
 
+/**
+ * Run one `--code` turn inside a persistent code session.
+ *
+ * `--session <id>` continues an existing one (the session carries the history,
+ * mode, model and agent); without it a fresh session is created and titled from
+ * the prompt. Either way the id is printed on stderr so the caller — a human or
+ * an agent shelling out — knows exactly which session to open in the panel.
+ */
+async function runCodeSessionTurn({ args, pid, prompt, model }) {
+  const flagged = args.flags.session;
+  let sid = typeof flagged === "string" && flagged.trim() ? flagged.trim() : null;
+  let created = false;
+
+  if (!sid) {
+    // No agentSlug here on purpose: `-a <slug>` never reaches this path — it
+    // sets useSuperAgent=false and routes to the agent's own exec endpoint.
+    const session = await http.post(`/api/projects/${pid}/code/sessions`, {
+      title: codeSessionTitle(prompt),
+      ...(model ? { model } : {}),
+    });
+    sid = session.id;
+    created = true;
+  }
+
+  const status = createExecStatus();
+  status.start();
+  let result;
+  try {
+    result = await http.streamPost(
+      `/api/projects/${pid}/code/sessions/${sid}/chat/stream`,
+      { prompt, channel: CHANNELS.CODE, cwd: process.cwd(), confirm: false },
+      (event) => status.set(labelForEvent(event))
+    );
+  } catch (e) {
+    // Name the session even on failure: the user turn is already stored there,
+    // so that is where the half-finished run can be inspected and resumed.
+    process.stderr.write(
+      `\n— code session ${sid}${created ? " (new)" : ""} | project ${pid} | ${http.baseUrl()}/code\n`
+    );
+    throw e;
+  } finally {
+    status.clear();
+  }
+
+  // A turn that produced no text is a failed turn, not an empty answer. Saying
+  // so beats a blank line and exit 0, which reads as "it worked, silently".
+  if (!result?.text) {
+    throw new Error(
+      `apx exec --code: the turn ended without a reply. Session ${sid} (project ${pid}) has the transcript: ${http.baseUrl()}/code`
+    );
+  }
+
+  process.stdout.write(result.text + "\n");
+  // Always tell the caller where the turn landed — a piped/scripted run needs
+  // the id to pass back as --session, and a human needs it to find the session
+  // in the panel. stderr keeps stdout clean for scripts.
+  process.stderr.write(
+    `\n— code session ${sid}${created ? " (new)" : ""} | project ${pid} | ${http.baseUrl()}/code\n`
+  );
+  if (process.stderr.isTTY || args.flags.verbose) {
+    process.stderr.write(
+      `— ${result.name || "super-agent"} | in=${result.usage?.input_tokens || "?"} out=${result.usage?.output_tokens || "?"}\n`
+    );
+  }
+}
+
 export async function cmdExec(args) {
   const { slug, useSuperAgent, promptParts } = resolveExecRequest(args);
   let prompt = promptParts.join(" ").trim();
@@ -152,15 +231,25 @@ export async function cmdExec(args) {
   }
 
   const pid = await resolveProjectId(args?.flags?.project);
+  const channel = resolveExecChannel(args);
   const body = {
     prompt,
-    channel: resolveExecChannel(args),
+    channel,
     channelMeta: { cwd: process.cwd() },
   };
   if (args.flags.model && args.flags.model !== true) body.model = args.flags.model;
   if (args.flags.temperature) body.temperature = parseFloat(args.flags.temperature);
   if (args.flags["max-tokens"]) body.maxTokens = parseInt(args.flags["max-tokens"], 10);
 
+  // The code channel runs through a persistent code session instead of the
+  // stateless super-agent route. Same output on stdout; the difference is that
+  // the turn is now READABLE afterwards in the web panel (/code) and by the
+  // next `--code` turn that continues the session, instead of existing only in
+  // whatever terminal happened to run it.
+  if (useSuperAgent && channel === CHANNELS.CODE) {
+    return runCodeSessionTurn({ args, pid, prompt, model: body.model });
+  }
+
   if (useSuperAgent) {
     // Stream the turn so we can render a live progress indicator instead of a
     // silent hang. `confirm: false` opts out of the interactive confirmation