@ctrl-spc/cs 0.7.9 → 0.7.11

package/dist/panel3/run.js

@@ -748,6 +748,17 @@ async function setCardState(client, cardId, state) {
         .select('id'), 'set the state of', `card ${cardId}`);
 }
 // ---------------------------------------------------------------------------
+/** Each start reloads only this run's durable choices, including null defaults. */
+export async function settingsForRun(client, runId) {
+    const rows = await returned(client.from('panel3_runs').select('model, effort, harness').eq('id', runId), 'read', `model and effort for run ${runId}`);
+    const row = rows[0];
+    if (!row || (row.harness !== null && row.harness !== 'claude' && row.harness !== 'codex')
+        || (row.model !== null && typeof row.model !== 'string')
+        || (row.effort !== null && typeof row.effort !== 'string')) {
+        throw new Error('The run has no readable harness, model and effort selection.');
+    }
+    return { model: row.model, effort: row.effort, harness: row.harness ?? undefined };
+}
 /**
  * One card, from the turns the take handed over to the answer on its thread.
  *
@@ -804,9 +815,11 @@ async function answerCard(client, tools, machineId, cardId, turns) {
        no rules" — that is a different project than the one the person is on. So it
        joins the three reads above inside this ending rather than beside it. */
     let rules;
+    let settings;
     try {
         brief = briefFor(turns[0].card_title, turns, await receiptsFor(client, cardId), await attachmentsFor(client, cardId), await codebasesForRun(client, runId));
         rules = await standingRulesFor(client, runId);
+        settings = await settingsForRun(client, runId);
         where = await workingDirectory(client, runId, LEVEL, false);
     }
     catch (error) {
@@ -823,7 +836,7 @@ async function answerCard(client, tools, machineId, cardId, turns) {
     /* AN EMPTY DIRECTORY OF THE USER'S OWN, because level 1 has no code tool to
        use a real one with, and the daemon's inherited cwd under a launchd login
        item is the filesystem root. */
-    const started = startAgent(withStandingRules(rules, brief, where.block), LEVEL, tools.urlFor(runId), where.cwd);
+    const started = startAgent(withStandingRules(rules, brief, where.block), LEVEL, tools.urlFor(runId), where.cwd, undefined, settings);
     out(`run      ${runId}  level ${LEVEL}  ${started.pid ? `pid ${started.pid}` : 'no process'}`);
     try {
         /* THE BRIEF, NOT WHAT THE PROCESS WAS HANDED. The rules are current at the
@@ -1162,14 +1175,16 @@ async function workingDirectory(client, runId, level, isOwner, knownCodebase) {
  * Then the row, then the process, then the pid — constraint 8, in the only order
  * that satisfies it.
  */
-async function startChild(client, tools, machineId, parentRunId, brief, codebase, parentProcessToken) {
+async function startChild(client, tools, machineId, parentRunId, brief, codebase, parentProcessToken, choice = {}) {
     const { data, error } = await client.rpc('panel3_dispatch', {
         p_parent_run_id: parentRunId,
         p_brief: brief,
         p_machine_id: machineId,
         p_codebase_id: codebase?.id ?? null,
         p_codebase_label: codebase?.name ?? null,
-        ...(parentProcessToken === undefined ? {} : { p_process_token: parentProcessToken }),
+        p_process_token: parentProcessToken ?? null,
+        p_model: choice.model ?? null,
+        p_effort: choice.effort ?? null,
     });
     if (error)
         throw new Error(`could not start an agent under run ${parentRunId}: ${readableWriteError(error.message)}`);
@@ -1200,12 +1215,14 @@ async function startChild(client, tools, machineId, parentRunId, brief, codebase
        exists (`panel3_dispatch` wrote it above) and it carries this child's
        codebase, which is what decides which codebase-scoped rules it is under. */
     let rules;
+    let settings;
     try {
         where = await workingDirectory(client, row.run_id, level, level === 2, codebase);
         prompt = level === 2
             ? await initialOwnerPrompt(client, row.run_card_id, parentRunId, brief)
             : brief;
         rules = await standingRulesFor(client, row.run_id);
+        settings = await settingsForRun(client, row.run_id);
         /* Inside this site's own try, for `standingRulesFor`'s reason: a failure to
            assemble what the agent needs ends the run the way this path already ends
            runs, rather than starting a process that is missing it. */
@@ -1218,7 +1235,7 @@ async function startChild(client, tools, machineId, parentRunId, brief, codebase
     }
     const processToken = row.process_token ?? undefined;
     const isOwner = level === 2;
-    const started = startAgent(withStandingRules(rules, prompt, where.block, [], pictures), level, tools.urlFor(row.run_id, processToken), where.cwd, isOwner ? { ownerId: row.run_id } : undefined);
+    const started = startAgent(withStandingRules(rules, prompt, where.block, [], pictures), level, tools.urlFor(row.run_id, processToken), where.cwd, isOwner ? { ownerId: row.run_id } : undefined, settings);
     if (started.pid === null) {
         /* THERE IS A ROW AND THERE IS NO PROCESS, which is the one shape the record
            must never be left in quietly. The answer is already settled — nothing ran
@@ -1688,9 +1705,11 @@ async function resumeRun(client, tools, machineId, runId, afterPid) {
        is a `returned()` message naming tables and columns, which carries no local
        path and is therefore shareable. */
     let rules;
+    let settings;
     let pictures;
     try {
         rules = await standingRulesFor(client, runId);
+        settings = await settingsForRun(client, runId);
         /* ═══ WRITTEN AGAIN ON EVERY START, LIKE THE RULES. ═══ A resumed process is
            a NEW process with a new copy of the working directory, so the files a
            previous one was handed are not there any more, and the stored brief this
@@ -1709,7 +1728,7 @@ async function resumeRun(client, tools, machineId, runId, afterPid) {
        still running. See `retryPrompt`. */
     withStandingRules(rules, afterPid === null
         ? resumePrompt(claimed.run_brief, claimed.run_report, children)
-        : retryPrompt(claimed.run_brief, claimed.run_report, children), where.block, [], pictures), level, tools.urlFor(runId), where.cwd);
+        : retryPrompt(claimed.run_brief, claimed.run_report, children), where.block, [], pictures), level, tools.urlFor(runId), where.cwd, undefined, settings);
     if (started.pid === null) {
         /* THE CLAIM HAPPENED AND NO PROCESS DID, which is the one shape the record
            must never be left in quietly. Same handling as a dispatch that could not
@@ -1816,9 +1835,11 @@ async function startRearmed(client, tools, machineId, row) {
        same way: the re-arm's claim has already happened, so a failure here ends
        the run with its reason rather than leaving it claimed with no process. */
     let rules;
+    let settings;
     let pictures;
     try {
         rules = await standingRulesFor(client, row.run_id);
+        settings = await settingsForRun(client, row.run_id);
         pictures = await picturesOnDisk(client, row.run_card_id, where, level);
     }
     catch (error) {
@@ -1826,7 +1847,7 @@ async function startRearmed(client, tools, machineId, row) {
         await endRun(client, level, row.run_id, row.run_card_id, why);
         throw new Error(`NO AGENT IS RUNNING: ${why}`);
     }
-    const started = startAgent(withStandingRules(rules, prompt, where.block, [], pictures), level, tools.urlFor(row.run_id), where.cwd);
+    const started = startAgent(withStandingRules(rules, prompt, where.block, [], pictures), level, tools.urlFor(row.run_id), where.cwd, undefined, settings);
     if (started.pid === null) {
         const answer = await started.answered;
         const reason = answer.ok ? 'the process ended before it could be identified' : answer.reason;
@@ -2064,6 +2085,7 @@ async function activateOwner(client, tools, machineId, runId, afterProcessToken
        says what the product DID with the person's answer, and the landing needs
        the card's copy. Nothing in the prompt depended on it before. */
     let rules;
+    let settings;
     /* THE CARD'S COPY IS MADE IN THE SAME WINDOW AND UNDER THE SAME ENDING, for
        the reason the check above gives: it writes, so it happens after the claim,
        and a failure to make it is an activation that ends rather than one that
@@ -2087,6 +2109,7 @@ async function activateOwner(client, tools, machineId, runId, afterProcessToken
     try {
         where = await ownerDirectory(client, candidate);
         rules = await standingRulesFor(client, runId);
+        settings = await settingsForRun(client, runId);
         attached = whatWasAttached((await attachmentsFor(client, claimed.run_card_id))
             .filter((line) => !line.startsWith('codebase  ')));
         /* ═══ THE OWNER'S OWN ACTIVATION, WHICH IS WHERE MOST PICTURES ARRIVE. ═══
@@ -2119,7 +2142,7 @@ async function activateOwner(client, tools, machineId, runId, afterProcessToken
            are not the same event and `prompt.ts` exists to stop an agent being
            told an untrue reason for its own restart. */
         afterPid !== null, landing);
-    const started = startAgent(withStandingRules(rules, prompt, where.block, attached, pictures), 2, tools.urlFor(runId, claimed.process_token), where.cwd, { ownerId: runId, ...(resumeSessionId ? { resumeSessionId } : {}) });
+    const started = startAgent(withStandingRules(rules, prompt, where.block, attached, pictures), 2, tools.urlFor(runId, claimed.process_token), where.cwd, { ownerId: runId, ...(resumeSessionId ? { resumeSessionId } : {}) }, settings);
     if (started.pid === null) {
         const answer = await started.answered;
         const reason = answer.ok ? 'the process ended before it could be identified' : answer.reason;
@@ -3100,8 +3123,8 @@ export async function run(args, injected) {
        `tools` is referenced inside the callback it is being given, which is safe
        for the plain reason that the callback can only run once a request has
        arrived at a server that by then exists. */
-    const tools = await startToolsServer(current(), async (parentRunId, brief, codebase, processToken) => {
-        const child = await startChild(current(), tools, machineId, parentRunId, brief, codebase, processToken);
+    const tools = await startToolsServer(current(), async (parentRunId, brief, codebase, processToken, choice) => {
+        const child = await startChild(current(), tools, machineId, parentRunId, brief, codebase, processToken, choice);
         hold(child.runId, child.settled);
         return { runId: child.runId };
     });

package/dist/panel3/show.js

@@ -83,7 +83,7 @@ const read = (query, what) => returned(query, 'read', what);
 const CARD_COLUMNS = 'id, project_id, title, state, created_at, archived_at';
 const TURN_COLUMNS = 'id, card_id, role, body, created_at, addressed_at, run_id';
 const RUN_COLUMNS = 'id, card_id, codebase_id, branch, parent_run_id, level, state, brief, report, failed_because, '
-    + 'activity, machine_id, pid, started_at, resumed_at, read_back_at, ended_at';
+    + 'activity, machine_id, pid, started_at, resumed_at, read_back_at, ended_at, model, effort';
 const ASK_COLUMNS = `id, card_id, run_id, pending_run_id, answered_at, delivered_at, created_at, ${ASK_CONTENT_COLUMNS}`;
 const OUTPUT_COLUMNS = 'id, card_id, run_id, kind, ref_id, label, created_at';
 const ATTACHMENT_COLUMNS = 'id, card_id, kind, ref_id, label, created_at';
@@ -1125,6 +1125,10 @@ async function showRun(client, run) {
     out(`RUN  ${run.id}`);
     out(`  card     ${run.card_id}${card ? `  ${card.title}` : '  (card not readable)'}`);
     out(`  level    ${run.level}`);
+    if (run.model != null)
+        out(`  model    ${run.model}`);
+    if (run.effort != null)
+        out(`  effort   ${run.effort}`);
     out(`  state    ${run.state}${isLive(run) ? '  (live)' : ''}`);
     out(`  parent   ${run.parent_run_id ?? 'none, dispatched by the daemon'}`);
     out(`  machine  ${run.machine_id}${run.pid ? `  pid ${run.pid}` : '  no pid recorded'}`);

package/dist/panel3/spawn.js

@@ -124,6 +124,7 @@ import { randomUUID } from 'node:crypto';
 import { agentPath } from '../agents.js';
 import { ensureCodexRunHome, ensurePanel3CodexOwnerHome, removeCodexRunHome, } from '../codex-home.js';
 import { windowsSafeSpawn } from '../win-shell.js';
+import { modelChoiceRules } from './prompt.js';
 const AGENT_VAR = 'CTRL_SPC_V3_AGENT';
 /**
  * The harness named on this machine, or the reason the name is not one.
@@ -169,9 +170,9 @@ const allowedTools = (level) => [`mcp__${SERVER}__*`, ...(level === 1 ? [] : COD
  * checked without starting a process — which is how the allowlist is proved,
  * and how it stays provable after this task.
  */
-export function agentArgs(level, toolsUrl, agent = harness(), platform = process.platform, ownerSession) {
+export function agentArgs(level, toolsUrl, agent = harness(), platform = process.platform, ownerSession, choice = {}) {
     if (agent === 'codex')
-        return codexArgs(level, toolsUrl, platform, ownerSession);
+        return codexArgs(level, toolsUrl, platform, ownerSession, choice);
     const session = ownerSession
         ? ownerSession.resumeSessionId
             ? ['--resume', ownerSession.resumeSessionId]
@@ -187,6 +188,8 @@ export function agentArgs(level, toolsUrl, agent = harness(), platform = process
         '--tools', builtIns(level),
         '--allowedTools', allowedTools(level),
         ...session,
+        ...(choice.model == null ? [] : ['--model', choice.model]),
+        ...(choice.effort == null ? [] : ['--effort', choice.effort]),
         /* STATED WHERE THERE IS SOMETHING TO STATE. `acceptEdits` grants file edits
            to a headless process with nobody at a prompt to approve them, and it is
            passed only to the levels that have a file tool to use it with: at level 1
@@ -221,7 +224,7 @@ export function agentArgs(level, toolsUrl, agent = harness(), platform = process
  * `--json` makes the answer an `agent_message` item read out of the stream
  * rather than whatever prose happened to reach stdout (see `codexAnswer`).
  */
-function codexArgs(level, toolsUrl, platform, ownerSession) {
+function codexArgs(level, toolsUrl, platform, ownerSession, choice = {}) {
     const resume = ownerSession?.resumeSessionId;
     return [
         'exec',
@@ -229,6 +232,8 @@ function codexArgs(level, toolsUrl, platform, ownerSession) {
         // The prompt arrives on stdin, exactly as it does for claude: `codex exec`
         // reads it from there when no prompt argument is given.
         '--json',
+        ...(choice.model == null ? [] : ['-m', choice.model]),
+        ...(choice.effort == null ? [] : ['-c', `model_reasoning_effort=${JSON.stringify(choice.effort)}`]),
         // The level 1 scratch directory is not a repository, and neither need a
         // working copy be.
         '--skip-git-repo-check',
@@ -241,13 +246,13 @@ function codexArgs(level, toolsUrl, platform, ownerSession) {
            proven per-run home below. */
         ...(platform === 'win32' ? [
             '--ignore-user-config',
-            '-c', 'model="gpt-5.5"',
             '-c', 'features.apps=false',
             // The same closing `codex-home.ts` writes into the per-run config, and
             // for the same measured reason: `features.multi_agent=false` parses and
             // leaves the tool reachable.
             '-c', 'agents.enabled=false',
             '-c', `mcp_servers.${SERVER}.url=${JSON.stringify(toolsUrl)}`,
+            '-c', `mcp_servers.${SERVER}.required=true`,
             '-c', `mcp_servers.${SERVER}.default_tools_approval_mode="approve"`,
             '-c', 'windows.sandbox="unelevated"',
             '-c', 'windows.sandbox_private_desktop=false',
@@ -291,7 +296,7 @@ function runKey(toolsUrl) {
  * is the forbidden state ux.md is about, so the failure wins wherever both are
  * present.
  */
-export function codexAnswer(stdout) {
+export function codexAnswer(stdout, exitCode = 0, stderr = '') {
     let text = null;
     let failure = null;
     for (const line of stdout.split('\n')) {
@@ -319,6 +324,9 @@ export function codexAnswer(stdout) {
     if (failure !== null) {
         return { ok: false, reason: `codex could not finish the turn${failure ? `: ${failure}` : ''}` };
     }
+    if (exitCode !== 0) {
+        return { ok: false, reason: `codex exited ${exitCode}${tail(stderr) || tail(stdout)}` };
+    }
     if (text === null || text.trim() === '') {
         return { ok: false, reason: 'codex exited 0 without saying anything to the person' };
     }
@@ -377,7 +385,7 @@ function tail(text, chars = 500) {
  * process still alive" after the daemon that started it has been killed. So the
  * caller gets the pid immediately, writes it, and then waits.
  */
-export function startAgent(prompt, level, toolsUrl, cwd, ownerSession) {
+export function startAgent(prompt, level, toolsUrl, cwd, ownerSession, settings = {}) {
     const failed = (reason) => ({
         pid: null,
         session: Promise.resolve(null),
@@ -385,7 +393,7 @@ export function startAgent(prompt, level, toolsUrl, cwd, ownerSession) {
     });
     let agent;
     try {
-        agent = harness();
+        agent = settings.harness ?? harness();
     }
     catch (err) {
         // A machine configured for a harness this build has never heard of. See
@@ -395,7 +403,10 @@ export function startAgent(prompt, level, toolsUrl, cwd, ownerSession) {
     const launchedOwnerSession = ownerSession && !ownerSession.resumeSessionId
         ? { ...ownerSession, freshSessionId: randomUUID() }
         : ownerSession;
-    const ARGS = agentArgs(level, toolsUrl, agent, process.platform, launchedOwnerSession);
+    // A local default applies only to an omitted choice; explicit run values always win.
+    const choice = { ...settings, model: settings.model ?? process.env[`CTRL_SPC_V3_${agent.toUpperCase()}_DEFAULT_MODEL`] };
+    const ARGS = agentArgs(level, toolsUrl, agent, process.platform, launchedOwnerSession, choice);
+    prompt = `${modelChoiceRules(agent)}\n\n${prompt}`;
     const bin = agentPath(agent);
     if (!bin) {
         return failed(`${agent} is not installed on this machine`);
@@ -531,6 +542,11 @@ export function startAgent(prompt, level, toolsUrl, cwd, ownerSession) {
                    respawn behind it is refused. Naming the signal is the whole fix. */
                 finish({ ok: false, reason: `${agent} was ended by ${signal}${tail(stderr) || tail(stdout)}` });
             }
+            else if (agent === 'codex') {
+                // Startup failures can put the real error in JSON stdout and only
+                // 'Reading prompt from stdin' on stderr, including on non-zero exits.
+                finish(codexAnswer(stdout, code ?? 1, stderr));
+            }
             else if (code !== 0) {
                 /* STDOUT WHEN STDERR IS EMPTY, because `claude -p` prints its own
                    failure on stdout and exits non-zero having written nothing to
@@ -541,11 +557,6 @@ export function startAgent(prompt, level, toolsUrl, cwd, ownerSession) {
             else if (stdout.trim() === '') {
                 finish({ ok: false, reason: `${agent} exited 0 and said nothing${tail(stderr)}` });
             }
-            else if (agent === 'codex') {
-                /* The stream, not the buffer. See `codexAnswer`: stdout here is
-                   protocol, and a failed turn that exited 0 is still a failure. */
-                finish(codexAnswer(stdout));
-            }
             else {
                 const text = stdout.trim();
                 finish({

package/dist/panel3/tools.js

@@ -1,3 +1,5 @@
+import { createEpicHandler, createSprintHandler, listStructureHandler, updateStructureHandler, listStructureArtifactsHandler, getStructureArtifactHandler, searchAgentCardsHandler, createStructureArtifactHandler, updateStructureArtifactHandler } from '../product-tools.js';
+import { listArtifactFoldersHandler, setArtifactFolderHandler, workItemDependencyHandler } from '../product-tools.js';
 /**
  * ═══ AGENT PANEL v3: the tools server, and the per-level allowlist. ═══
  *
@@ -789,6 +791,36 @@ const TOOLS = [
             return `Created Product Idea ${a.title}, id ${id}. No work has started. Only a human can promote it.`;
         },
     },
+    {
+        name: 'list_artifact_folders', levels: ALL,
+        description: 'Read existing artifact folder names and counts before choosing a folder.',
+        input: { work_item_id: z.string().uuid() },
+        handler: async (caller, args) => productResult(await listArtifactFoldersHandler(caller.client, args.work_item_id)),
+    },
+    {
+        name: 'set_artifact_folder', levels: ALL,
+        description: 'Move an artifact into one folder, replacing its previous folder. Null clears it to Unfiled. Content and approval stay unchanged.',
+        input: { artifact_id: z.string().uuid(), folder_name: z.string().max(80).nullable() },
+        handler: async (caller, args) => productResult(await setArtifactFolderHandler(caller.client, args.artifact_id, args.folder_name)),
+    },
+    {
+        name: 'list_work_item_dependencies', levels: ALL,
+        description: 'Read blockers, dependents, and whether this work item is waiting.',
+        input: { work_item_id: z.string().uuid(), },
+        handler: async (caller, args) => productResult(await workItemDependencyHandler(caller.client, 'list', args)),
+    },
+    {
+        name: 'add_work_item_dependency', levels: [1, 2],
+        description: 'Make work_item_id wait for depends_on_work_item_id to reach Done. Same-project work items only; self-links and cycles are refused.',
+        input: { work_item_id: z.string().uuid(), depends_on_work_item_id: z.string().uuid(), },
+        handler: async (caller, args) => productResult(await workItemDependencyHandler(caller.client, 'add', args)),
+    },
+    {
+        name: 'remove_work_item_dependency', levels: [1, 2],
+        description: 'Remove exactly this dependency edge without changing either work item status.',
+        input: { work_item_id: z.string().uuid(), depends_on_work_item_id: z.string().uuid(), },
+        handler: async (caller, args) => productResult(await workItemDependencyHandler(caller.client, 'remove', args)),
+    },
     {
         name: 'place_work_item', levels: [1],
         description: 'Move a work item into an epic or sprint in its project. Null removes placement. Its status stays the same.',
@@ -964,7 +996,7 @@ const TOOLS = [
                 .from('tasks')
                 .select('id, name, description, status, due_date, project_id, created_at, epics(name), sprints(name)')
                 .eq('id', work_item_id), 'read', `work item ${work_item_id}`);
-            const artifacts = await rows(client.from('artifacts').select('id, type, title, created_at').eq('task_id', work_item_id)
+            const artifacts = await rows(client.from('artifacts').select('id, type, title, created_at, folder_name').eq('task_id', work_item_id)
                 .is('deleted_at', null).order('created_at'), 'read', `the artifacts on work item ${work_item_id}`);
             const feedback = await rows(client.from('artifact_feedback').select('*').eq('task_id', work_item_id).order('created_at'), 'read', 'the artifact feedback');
             const decisions = await rows(client.from('decisions').select('id, category, question, state, selected_options, answer_note, related_artifact_id').eq('task_id', work_item_id).order('asked_at'), 'read', 'the work item decisions');
@@ -983,7 +1015,7 @@ const TOOLS = [
                 '',
                 'DECISIONS', JSON.stringify(decisions), 'FEEDBACK', JSON.stringify(feedback), 'COMMENTS', JSON.stringify(comments),
                 `ARTIFACTS  ${artifacts.length}`,
-                listed(artifacts.map((a) => line(a.id, a.type, a.title ?? '(untitled)')), 'none'),
+                listed(artifacts.map((a) => line(a.id, a.type, a.title ?? '(untitled)', `folder: ${a.folder_name ?? 'Unfiled'}`)), 'none'),
             ].join('\n');
         },
     },
@@ -1681,9 +1713,9 @@ const TOOLS = [
         input: { work_item_id: z.string() },
         handler: async ({ client }, args) => {
             const { work_item_id } = args;
-            const artifacts = await rows(client.from('artifacts').select('id, type, format, title, created_at').eq('task_id', work_item_id)
+            const artifacts = await rows(client.from('artifacts').select('id, type, format, title, created_at, folder_name').eq('task_id', work_item_id)
                 .is('deleted_at', null).order('created_at'), 'read', `the artifacts on work item ${work_item_id}`);
-            return listed(artifacts.map((a) => line(a.id, a.type, a.format, a.title ?? '(untitled)')), 'That work item has no artifacts.');
+            return listed(artifacts.map((a) => line(a.id, a.type, a.format, a.title ?? '(untitled)', `folder: ${a.folder_name ?? 'Unfiled'}`)), 'That work item has no artifacts.');
         },
     },
     {
@@ -1694,7 +1726,7 @@ const TOOLS = [
         handler: async ({ client }, args) => {
             const { artifact_id } = args;
             const artifact = await only(client.from('artifacts')
-                .select('id, task_id, type, format, title, content, storage_path, revision, created_at')
+                .select('id, task_id, type, format, title, content, storage_path, revision, created_at, folder_name')
                 .eq('id', artifact_id), 'read', `artifact ${artifact_id}`);
             return [
                 `${artifact.title ?? '(untitled)'}`,
@@ -1702,6 +1734,7 @@ const TOOLS = [
                 `work item    ${artifact.task_id}`,
                 `type         ${artifact.type} (${artifact.format})`,
                 `revision     ${artifact.revision}`,
+                `folder       ${artifact.folder_name ?? 'Unfiled'}`,
                 '',
                 /* A stored file and an empty body are different facts and are said
                    differently. Returning '' for a PNG would read as an artifact with
@@ -1833,11 +1866,11 @@ const TOOLS = [
             const agents = await rows(client.from('panel3_runs')
                 // `resumed_at` is read because "how long it has been going" is about
                 // the attempt that is running now. See `elapsed`.
-                .select('id, level, parent_run_id, state, activity, started_at, resumed_at, ended_at')
+                .select('id, level, parent_run_id, state, activity, started_at, resumed_at, ended_at, model, effort')
                 .eq('card_id', cardId).order('started_at'), 'read', 'the agents on this card');
             return listed(agents.map((a) => {
                 const live = a.state === 'running' && !a.ended_at;
-                return line(a.id, `L${a.level}`, a.parent_run_id ? `parent ${a.parent_run_id}` : 'no parent, dispatched by the daemon', live ? 'still running' : a.state, a.activity ?? null, live
+                return line(a.id, `L${a.level}`, a.parent_run_id ? `parent ${a.parent_run_id}` : 'no parent, dispatched by the daemon', live ? 'still running' : a.state, a.activity ?? null, a.model == null ? null : `model ${a.model}`, a.effort == null ? null : `effort ${a.effort}`, live
                     ? `going ${elapsed(a.started_at, null, a.resumed_at)}`
                     : `went ${elapsed(a.started_at, a.ended_at, a.resumed_at)}`);
             }), 'Nothing has run on this card.');
@@ -1851,9 +1884,11 @@ const TOOLS = [
             + 'in your prompt; this is here for when you need to re-read them mid-run.',
         input: {},
         handler: async ({ client, runId }) => {
-            const run = await only(client.from('panel3_runs').select('level, brief, report, activity').eq('id', runId), 'read', 'your own run');
+            const run = await only(client.from('panel3_runs').select('level, brief, report, activity, model, effort').eq('id', runId), 'read', 'your own run');
             return [
                 `You are a level ${run.level} agent.`,
+                ...(run.model == null ? [] : [`MODEL  ${run.model}`]),
+                ...(run.effort == null ? [] : [`EFFORT  ${run.effort}`]),
                 '',
                 'BRIEF, written when you were dispatched and never changed',
                 run.brief,
@@ -1878,9 +1913,9 @@ const TOOLS = [
             + 'dispatch the same work twice.',
         input: {},
         handler: async ({ client, runId }) => {
-            const children = await rows(client.from('panel3_runs').select('id, level, state, activity, started_at, ended_at')
+            const children = await rows(client.from('panel3_runs').select('id, level, state, activity, started_at, ended_at, model, effort')
                 .eq('parent_run_id', runId).order('started_at'), 'read', 'the runs you dispatched');
-            return listed(children.map((c) => line(c.id, `L${c.level}`, c.state === 'running' && !c.ended_at ? 'still running' : c.state, c.activity ?? null)), 'You have dispatched nothing.');
+            return listed(children.map((c) => line(c.id, `L${c.level}`, c.state === 'running' && !c.ended_at ? 'still running' : c.state, c.activity ?? null, c.model == null ? null : `model ${c.model}`, c.effort == null ? null : `effort ${c.effort}`)), 'You have dispatched nothing.');
         },
     },
     {
@@ -2046,34 +2081,65 @@ const TOOLS = [
         },
     },
     {
-        name: 'create_epic',
-        levels: [1],
-        description: 'Create an epic in a project. An epic groups work items that belong to one body of work.',
-        input: { project_id: z.string(), name: z.string().min(1) },
+        name: 'create_epic', levels: [1, 2],
+        description: 'Create an epic with optional description and dates. Read list_structure first to avoid duplicates.',
+        input: { project_id: z.string().uuid(), name: z.string().min(1), description: z.string().optional(), start_date: z.string().optional(), target_date: z.string().optional() },
         handler: async (caller, args) => {
-            const { project_id, name } = args;
-            const epic = await only(caller.client.from('epics').insert({ project_id, name }).select('id, name'), 'create', `an epic called ${name}`);
-            await receipt(caller, 'epic', epic.id, epic.name);
-            return `Created epic ${epic.name}, id ${epic.id}.`;
+            const text = productResult(await createEpicHandler(caller.client, args));
+            const row = JSON.parse(text).epic;
+            await receipt(caller, 'epic', row.id, row.name);
+            return text;
         },
     },
     {
-        name: 'create_sprint',
-        levels: [1],
-        description: 'Create an ordered batch of work in a project. Dates are optional; use them only for a stated calendar constraint.',
-        input: {
-            project_id: z.string(),
-            name: z.string().min(1),
-            start_date: z.string().optional().describe('YYYY-MM-DD'),
-            end_date: z.string().optional().describe('YYYY-MM-DD'),
-        },
+        name: 'create_sprint', levels: [1, 2],
+        description: 'Create an sprint with optional description and dates. Read list_structure first to avoid duplicates.',
+        input: { project_id: z.string().uuid(), name: z.string().min(1), description: z.string().optional(), start_date: z.string().optional(), end_date: z.string().optional() },
         handler: async (caller, args) => {
-            const { project_id, name, start_date, end_date } = args;
-            const sprint = await only(caller.client.from('sprints').insert({ project_id, name, start_date, end_date }).select('id, name'), 'create', `a sprint called ${name}`);
-            await receipt(caller, 'sprint', sprint.id, sprint.name);
-            return `Created sprint ${sprint.name}, id ${sprint.id}.`;
+            const text = productResult(await createSprintHandler(caller.client, args));
+            const row = JSON.parse(text).sprint;
+            await receipt(caller, 'sprint', row.id, row.name);
+            return text;
         },
     },
+    {
+        name: 'list_structure', levels: ALL,
+        description: 'Read project epics and sprints with their descriptions and dates.',
+        input: { project_id: z.string().uuid() },
+        handler: async (caller, args) => productResult(await listStructureHandler(caller.client, { project_id: args.project_id })),
+    },
+    {
+        name: 'update_structure', levels: [1, 2],
+        description: 'Edit an epic or sprint name, description, dates, or archive state. Null clears a date. Epics use target_date; sprints use end_date.',
+        input: { kind: z.enum(['epic', 'sprint']), id: z.string().uuid(), name: z.string().min(1).optional(), description: z.string().optional(), start_date: z.string().nullable().optional(), end_date: z.string().nullable().optional(), target_date: z.string().nullable().optional(), archived: z.boolean().optional() },
+        handler: async (caller, args) => productResult(await updateStructureHandler(caller.client, args)),
+    },
+    {
+        name: 'search_agent_cards', levels: ALL,
+        description: 'Find your agent conversations by literal title or message text, or by work item. Includes archived cards unless specified. Follow next_offset for remaining results. Read-only.',
+        input: { query: z.string().max(500).optional(), work_item_id: z.string().uuid().optional(), archived: z.boolean().optional(), limit: z.number().int().min(1).max(1000).optional(), offset: z.number().int().min(0).optional() },
+        handler: async (caller, args) => productResult(await searchAgentCardsHandler(caller.client, args)),
+    },
+    {
+        name: 'list_structure_artifacts', levels: ALL, description: 'Read active artifacts attached directly to an epic or sprint.',
+        input: { kind: z.enum(['epic', 'sprint']), structure_id: z.string().uuid() },
+        handler: async (caller, args) => productResult(await listStructureArtifactsHandler(caller.client, args.kind, args.structure_id)),
+    },
+    {
+        name: 'get_structure_artifact', levels: ALL, description: 'Read a full epic or sprint artifact and its current revision.',
+        input: { artifact_id: z.string().uuid() },
+        handler: async (caller, args) => productResult(await getStructureArtifactHandler(caller.client, args.artifact_id)),
+    },
+    {
+        name: 'create_structure_artifact', levels: ALL, description: 'Create a titled artifact on an epic or sprint. It appears on its management page.',
+        input: { kind: z.enum(['epic', 'sprint']), structure_id: z.string().uuid(), title: z.string().min(1).max(200), type: z.enum(['analysis', 'plan', 'spec', 'user_story', 'diagram', 'mock', 'wireframe']), format: z.enum(['md', 'html', 'json', 'svg']).optional(), content: z.string().min(1) },
+        handler: async (caller, args) => { const text = productResult(await createStructureArtifactHandler(caller.client, caller.userId, args)); const result = JSON.parse(text); await receipt(caller, result.kind, result.structure.id, result.structure.name); return text; },
+    },
+    {
+        name: 'update_structure_artifact', levels: ALL, description: 'Update an epic or sprint artifact using the revision you read. Concurrent edits refuse without overwriting. archived=true removes it; false restores it.',
+        input: { artifact_id: z.string().uuid(), expected_revision: z.number().int().positive(), title: z.string().min(1).max(200).optional(), type: z.enum(['analysis', 'plan', 'spec', 'user_story', 'diagram', 'mock', 'wireframe']).optional(), format: z.enum(['md', 'html', 'json', 'svg']).optional(), content: z.string().optional(), archived: z.boolean().optional() },
+        handler: async (caller, args) => productResult(await updateStructureArtifactHandler(caller.client, args)),
+    },
     {
         name: 'create_work_item',
         levels: [1],
@@ -2176,6 +2242,7 @@ const TOOLS = [
             + FIREWALL_WRITING_RULE,
         input: {
             work_item_id: z.string(),
+            folder_name: z.string().max(80).nullable().optional().describe('Read list_artifact_folders first to reuse a folder.'),
             title: z.string().min(1),
             content: z.string().min(1),
             type: z.enum(['plan', 'spec', 'analysis', 'diagram', 'mock', 'wireframe', 'user_story']).optional(),
@@ -2185,6 +2252,7 @@ const TOOLS = [
             const a = args;
             const artifact = await only(caller.client.from('artifacts').insert({
                 task_id: a.work_item_id,
+                folder_name: a.folder_name ?? null,
                 title: a.title,
                 content: a.content,
                 type: a.type ?? 'plan',
@@ -2894,6 +2962,8 @@ const TOOLS = [
                 + 'context: what to find out or change, and in which part of the codebase.'),
             boundary: z.string().min(1).describe('What it must not touch, and where its work stops.'),
             work_item_id: z.string().optional().describe('The work item it is working, if there is one.'),
+            model: z.string().min(1).optional().describe('Exact model for this child. Copy the user\'s applicable value verbatim, including aliases; never expand or normalize it. Otherwise choose for the task. Omit for the harness or machine default, never parent inheritance.'),
+            effort: z.string().min(1).optional().describe('Exact effort for this child. Honor the user\'s applicable wish; otherwise choose independently. Passed unchanged to the harness.'),
             work_name: z.string().optional().describe(`A few words, ${WORK_NAME_WORDS} at most, naming the WORK this conversation is doing, such `
                 + 'as "Fix the sign-out checklist bug". Pass it when the conversation has NO work item '
                 + 'attached: the conversation is called this from now on, and the branch the work goes on is '
@@ -2901,7 +2971,7 @@ const TOOLS = [
                 + 'attached, because that item is already the name.'),
         },
         handler: async (caller, args) => {
-            const { codebase_id, responsibility, boundary, work_item_id, work_name } = args;
+            const { codebase_id, responsibility, boundary, work_item_id, work_name, model, effort } = args;
             if (caller.level === 2 && !codebase_id) {
                 throw new Error('A worker must be attached to a registered project codebase.');
             }
@@ -2964,7 +3034,7 @@ const TOOLS = [
             const attachments = attached.map(attachmentLine);
             const { runId } = await caller.dispatch(caller.runId, workBrief(childLevel, responsibility, boundary, work_item_id, attachments, codebase === null ? undefined : {
                 id: codebase.id, name: codebase.name, identity: codebase.gitRemoteUrl,
-            }), codebase, caller.processToken);
+            }), codebase, caller.processToken, { model, effort });
             /* ═══ WHERE ITS ANSWER GOES DEPENDS ON WHICH LEVEL THIS IS, AND THAT IS
                KNOWN HERE RATHER THAN GUESSED. ═══ The description above cannot say it,
                because it is registered once for both levels that hold the tool; this