@ctrl-spc/cs 0.6.0 → 0.7.1

package/dist/work-context.js

@@ -0,0 +1,1484 @@
+import { statSync } from 'node:fs';
+import { readCodebasePaths } from './config.js';
+export const EMPTY_WORK_CONTEXT = {
+    items: [],
+    checkout: null,
+    gitRemoteUrl: null,
+    miss: null,
+};
+const LINK_KINDS = [
+    'work-item',
+    'epic',
+    'sprint',
+    'skill',
+    'credential',
+    'workflow',
+];
+/** The kind of ONE link row, defaulting to `'work-item'` — see `AttachedKind`.
+ *
+ *  18d SLICE 1: this returns the REAL kind for all six, where it used to
+ *  collapse everything it did not recognise into `'work-item'`. That collapse
+ *  was safe while the only unrecognised kinds were hypothetical; once the
+ *  drawer writes three of them it became actively wrong, sending a skill's uuid
+ *  into the `tasks` read and, worse, past `readAttachedStructureProject`'s
+ *  `!== 'work-item'` filter into the `sprints` read.
+ *
+ *  The fallback SURVIVES for genuinely unrecognised kinds, for the reason
+ *  `AttachedKind` gives: a kind this build has never heard of is a newer
+ *  writer's, and dropping the link would silently lose something the user did. */
+function linkKind(row) {
+    const kind = row.kind;
+    return LINK_KINDS.includes(kind) ? kind : 'work-item';
+}
+/**
+ * EVERY attachment on a request, resolved to something a worker can read.
+ *
+ * `workItemForTodo` in orchestrator.ts already reads this table, but takes
+ * `.limit(1)` because the SCOPE GATE only needs one unapproved item to refuse.
+ * That limit is correct there and wrong here: I6 is precisely that only the
+ * first attachment ever reached the worker.
+ *
+ * Two reads rather than a join, because `cliv2_loose_todo_links.work_item_id`
+ * is a BY-VALUE reference with no foreign key (AGENTS.md: a `cliv2_*` row never
+ * couples structurally to a v1-owned table), so PostgREST cannot embed `tasks`
+ * through a relationship that does not exist in the schema.
+ *
+ * A link pointing at a deleted task RESOLVES TO NOTHING and is dropped, which
+ * is the visible degradation the link table's own migration argues for.
+ *
+ * 18b SLICE 6 — ONLY THE WORK-ITEM LINKS ARE READ FROM `tasks`, and the filter
+ * is what makes that read correct rather than merely narrower. An epic's id is
+ * not in `tasks`, so before this filter an epic link went into the `in (...)`
+ * list, matched nothing, and was dropped as if it pointed at a DELETED work item
+ * — the two states are indistinguishable once the kind is thrown away. That
+ * mattered because of what the caller does next: `buildWorkContext` returns
+ * `EMPTY_WORK_CONTEXT` on `items.length === 0`, so a request attached ONLY to an
+ * epic lost its checkout AND its project, and per Slice 2 a code-capable run then
+ * refused or ran nowhere. Filtering here keeps the epic out of a read that could
+ * never have resolved it, and `readAttachedStructure` below is what stops the
+ * request losing its project because of it.
+ *
+ * READING THE EPIC OR SPRINT ITSELF IS SLICE 6b, deliberately not here. Slice 6
+ * attaches; 6b describes. What this function owes Slice 6 is that attaching an
+ * epic does not COST the request anything it already had.
+ */
+export async function readAttachedItems(client, todoId) {
+    const { data: links, error: linkError } = await client
+        .from('cliv2_loose_todo_links')
+        .select('work_item_id, kind, created_at')
+        .eq('todo_id', todoId)
+        .order('created_at', { ascending: true });
+    if (linkError)
+        throw new Error(linkError.message);
+    const ids = (links ?? [])
+        .filter((row) => linkKind(row) === 'work-item')
+        .map((row) => row.work_item_id)
+        .filter((id) => typeof id === 'string' && id !== '');
+    if (ids.length === 0)
+        return [];
+    const { data: tasks, error: taskError } = await client
+        .from('tasks')
+        .select('id, name, description, is_idea, project_id, projects(name)')
+        .in('id', ids);
+    if (taskError)
+        throw new Error(taskError.message);
+    /* Indexed, then emitted IN LINK ORDER. The `in` read comes back in whatever
+       order the server chose, and the user attached these one at a time — the
+       first one they picked reading third would be a small, permanent lie about
+       what they did. */
+    const byId = new Map();
+    for (const row of tasks ?? []) {
+        const task = row;
+        const project = Array.isArray(task.projects) ? task.projects[0] : task.projects;
+        byId.set(task.id, {
+            id: task.id,
+            name: task.name,
+            description: task.description ?? '',
+            isIdea: task.is_idea === true,
+            projectId: task.project_id,
+            projectName: project?.name ?? '',
+        });
+    }
+    return ids.map((id) => byId.get(id)).filter((item) => item !== undefined);
+}
+/**
+ * 18b SLICE 6 — THE PROJECT AN ATTACHED EPIC OR SPRINT BELONGS TO.
+ *
+ * THE ONE FACT SLICE 6 NEEDS OUT OF AN EPIC, and deliberately the only one. The
+ * name, the description, the sprints underneath it and the backlog order are all
+ * Slice 6b's, and none of them are read here. This answers a single question:
+ * WHICH PROJECT, so a request attached only to an epic can still resolve its
+ * codebase and still refuse honestly when it cannot.
+ *
+ * WITHOUT IT THE ATTACHMENT COSTS THE USER THE RUN. `resolveWorkContext` returns
+ * `EMPTY_WORK_CONTEXT` when no work item resolves, and Slice 2 gates the tick's
+ * refusal on `miss` being non-null — so an epic-only code request would neither
+ * run in the right place nor say why. Attaching MORE context must never leave a
+ * request with LESS than it had.
+ *
+ * IDS ONLY, NEVER A PATH. Same invariant as everything else in this module: what
+ * comes back is a project id, which travels to `resolveProjectContext` and turns
+ * into a cwd locally. Nothing here reaches a prompt or a column.
+ *
+ * THE FIRST ATTACHMENT WINS, matching the work-item path exactly (`items[0]`
+ * decides the directory). Two epics in two projects has no single right answer,
+ * and guessing between them is the failure this module refuses everywhere else.
+ *
+ * BEST-EFFORT, LIKE EVERY OTHER READ IN THE TICK. `epics` and `sprints` are
+ * v1-owned product tables read through the user's own RLS, exactly as the web
+ * app reads them (AGENTS.md permits the read; it is v2's WRITES that must stay
+ * in `cliv2_*`). A failure returns null and the caller degrades to "no project",
+ * which refuses — rather than throwing and costing the user the request.
+ */
+export async function readAttachedStructureProject(client, todoId) {
+    const { data: links, error: linkError } = await client
+        .from('cliv2_loose_todo_links')
+        .select('work_item_id, kind, created_at')
+        .eq('todo_id', todoId)
+        .order('created_at', { ascending: true });
+    if (linkError)
+        throw new Error(linkError.message);
+    /* In attach order, so "the first one" means the first the user picked — the
+       same promise `readAttachedItems` keeps about its own ordering. */
+    /* 18d SLICE 1 — NAMED, NOT "EVERYTHING THAT IS NOT A WORK ITEM". This filter
+       used to read `!== 'work-item'`, which was exhaustive while the column held
+       three kinds and became a bug the moment it held six: a selected skill would
+       have counted as structural and had its uuid queried against `sprints`. The
+       two kinds this function can actually resolve are named. */
+    const structural = (links ?? [])
+        .map((row) => ({ id: row.work_item_id, kind: linkKind(row) }))
+        .filter((row) => (row.kind === 'epic' || row.kind === 'sprint') && typeof row.id === 'string' && row.id !== '');
+    if (structural.length === 0)
+        return null;
+    const first = structural[0];
+    /* The TABLE is chosen by the kind, because that is the only thing that
+       distinguishes the two ids. Querying both and taking whichever hit would
+       resolve a sprint id that happened to collide with an epic id, which is the
+       kind of "works until it does not" this module's comments exist to prevent. */
+    const table = first.kind === 'epic' ? 'epics' : 'sprints';
+    /* 18b SLICE 6b — THE NAME COMES BACK TOO, not just the project.
+       Slice 6 read only what it needed to resolve a checkout, and deliberately
+       stopped there. But the agent was then never told WHICH epic the request was
+       about: asked to "summarise this epic's sprints", it had a working directory
+       and no idea what "this epic" referred to. The name and id are on the row
+       this query already fetches, so carrying them costs nothing. */
+    const { data, error } = await client
+        .from(table)
+        .select('id, name, project_id, projects(name)')
+        .eq('id', first.id)
+        .limit(1);
+    if (error)
+        throw new Error(error.message);
+    const row = (data ?? [])[0];
+    if (!row?.project_id)
+        return null;
+    const project = Array.isArray(row.projects) ? row.projects[0] : row.projects;
+    return {
+        id: row.id,
+        /* `kind` comes from the LINK, not from the row: it is what chose the table,
+           and the row itself carries no such column. */
+        kind: first.kind === 'epic' ? 'epic' : 'sprint',
+        name: row.name ?? '',
+        projectId: row.project_id,
+        projectName: project?.name ?? '',
+    };
+}
+/**
+ * THE CODEBASE A WORK ITEM MEANS, as a canonical `host/path` identity.
+ *
+ * TARGETS FIRST. `cliv2_task_codebase_targets` is the work item saying which
+ * codebase it is about, and a project may hold several. Falling straight to
+ * "the project's codebase" would put the worker in the wrong repo of the right
+ * project whenever the item had bothered to say.
+ *
+ * THEN THE PROJECT'S ONE CODEBASE, and only when there is exactly one. With two
+ * and no target there is no answer, and picking the oldest would be a guess
+ * dressed as a resolution — the Gherkin's "does not silently work in the wrong
+ * directory" forbids exactly that.
+ */
+export async function resolveCodebaseRemote(client, item) {
+    const { data: targets, error: targetError } = await client
+        .from('cliv2_task_codebase_targets')
+        .select('git_remote_url, created_at')
+        .eq('task_id', item.id)
+        .order('created_at', { ascending: true })
+        .limit(1);
+    if (targetError)
+        throw new Error(targetError.message);
+    const targeted = (targets ?? [])[0];
+    if (targeted?.git_remote_url)
+        return targeted.git_remote_url;
+    const { data: codebases, error: codebaseError } = await client
+        .from('cliv2_codebases')
+        .select('git_remote_url, created_at')
+        .eq('project_id', item.projectId)
+        .order('created_at', { ascending: true })
+        .limit(2);
+    if (codebaseError)
+        throw new Error(codebaseError.message);
+    const rows = (codebases ?? []);
+    /* EXACTLY ONE, or nothing. Two codebases and no target is genuinely ambiguous
+       and the honest answer is to refuse — see the header. */
+    return rows.length === 1 ? rows[0].git_remote_url : null;
+}
+/**
+ * 18b SLICE 2 — THE SAME QUESTION, ASKED OF A PROJECT INSTEAD OF A WORK ITEM.
+ *
+ * A request typed with nothing attached has no work item to resolve through, so
+ * there is no target to consult and no `AttachedItem` to carry a project name.
+ * It has one thing: the `project_id` the user chose in the composer (Slice 1).
+ * This is the whole resolution available to it — straight to the project's
+ * codebases, with nothing to break a tie.
+ *
+ * IT RETURNS THE CANDIDATES RATHER THAN A BOOLEAN, because the three outcomes
+ * need three different sentences on the card: none registered, exactly one (run
+ * there), or several with no target (say WHICH several). `resolveCodebaseRemote`
+ * collapses the first and third into `null`, which is why a user with two
+ * codebases was told they had none.
+ *
+ * `limit(3)` rather than `limit(2)`: the refusal names the candidates, so it
+ * needs more than "there is more than one". Three is enough to write an honest
+ * sentence without reading a project's entire codebase list into memory.
+ */
+export async function resolveProjectCodebases(client, projectId) {
+    const { data, error } = await client
+        .from('cliv2_codebases')
+        .select('git_remote_url, created_at')
+        .eq('project_id', projectId)
+        .order('created_at', { ascending: true })
+        .limit(3);
+    if (error)
+        throw new Error(error.message);
+    return (data ?? []).map(r => r.git_remote_url);
+}
+/**
+ * EVERYTHING THE WORKER NEEDS, for one request.
+ *
+ * NEVER THROWS on the codebase half. The attachments are the load-bearing read
+ * (they carry I6's title, description and project); the checkout is a bonus
+ * that a question-answering request does not need at all. A failed codebase
+ * lookup therefore degrades to "no directory" — the worker still runs, with the
+ * `not-located` shape the caller reports — rather than costing the user the run.
+ *
+ * The FIRST attached item decides the directory. A request touching two items in
+ * two repos has no single right answer, and the scope gate already refuses to
+ * dispatch a unit whose items are not all approved.
+ */
+export async function resolveWorkContext(client, todoId, warn = console.warn, 
+/** Injected so the resolution is testable without writing the real user's
+ *  config file. Production always uses the real one. */
+codebasePaths = readCodebasePaths, 
+/** Injected for the same reason — a test must not depend on which folders
+ *  happen to exist on the machine running it. */
+folderExists = defaultFolderExists, 
+/** 18b SLICE 4, THE CODEBASE THE USER CHOSE, for an ATTACHED request.
+ *
+ *  The unattached path has carried this since Slice 4. This one could not,
+ *  so an attached request that was asked which codebase had nowhere to put
+ *  the answer and would have been asked again on every tick forever. */
+chosenRemote = null) {
+    let items = [];
+    try {
+        items = await readAttachedItems(client, todoId);
+    }
+    catch (err) {
+        /* Best-effort, like every other prompt input in the tick. A failed read
+           costs the worker its context, which is bad; failing the dispatch costs
+           the user their work, which is worse. */
+        warn(`[orchestrator] could not read what this request is attached to: ${err.message}`);
+        return EMPTY_WORK_CONTEXT;
+    }
+    /* 18b SLICE 6 — NO WORK ITEM IS NOT THE SAME AS NOTHING ATTACHED.
+       A request attached only to an EPIC or a SPRINT resolves no `AttachedItem`
+       (they are not `tasks` rows), and returning the empty context here would cost
+       it its checkout and its project — so a code-capable run would refuse or run
+       nowhere, which is strictly worse than the same request with NOTHING attached.
+       The structure still names a project, so the request resolves through it by
+       exactly the path an unattached request uses (`resolveProjectContext`), and
+       gets the same checkout and the same honest refusals.
+  
+       18b SLICE 6b — AND THE STRUCTURE ITSELF NOW TRAVELS. Slice 6 carried only
+       the project out of here, because naming the epic to the agent was 6b's job.
+       It is now done: the resolved context keeps the epic or sprint, so
+       `describeStructure` can tell the agent WHICH one the request is about. The
+       checkout resolution below is unchanged — the project is still what decides
+       the directory. */
+    if (items.length === 0) {
+        let structure = null;
+        try {
+            structure = await readAttachedStructureProject(client, todoId);
+        }
+        catch (err) {
+            warn(`[orchestrator] could not read the attached epic or sprint: ${err.message}`);
+        }
+        if (!structure)
+            return EMPTY_WORK_CONTEXT;
+        const context = await resolveProjectContext(client, structure.projectId, structure.projectName, warn, codebasePaths, folderExists);
+        /* Attached to the RESOLVED context, whatever it turned out to be. A miss is
+           still a context: the request refuses, and the card that says why is better
+           for naming the epic it was about. */
+        return { ...context, structure };
+    }
+    const primary = items[0];
+    /* ═══ THE ANSWER WINS OVER THE MEMORY. ═══
+       `chosenRemote` is the user answering "which codebase should this run in?"
+       for THIS request, seconds ago; a target is what some earlier answer left on
+       the work item. When both exist the newer statement is the operative one, and
+       it is resolved by exactly the path an unattached answer takes.
+  
+       18b SLICE 9 MAKES THIS REACHABLE AND LOAD-BEARING. Keeping a choice writes
+       the target, so from that moment the request that was just answered has both.
+       Picking TWO and keeping both writes two targets in one statement, sharing a
+       `created_at`, so "the oldest target" is not a defined order, and without
+       this the run could land in the other one of the two the user picked.
+  
+       THROUGH THE PROJECT RESOLVER, not straight to the folder, because that is
+       where a chosen codebase is CHECKED against the project's own list before it
+       is used. An answer can name a codebase the project no longer has (it was
+       detached between the question and the answer), and running there would be
+       worse than asking again. One verification, both paths. */
+    if (chosenRemote) {
+        const chosenContext = await resolveProjectContext(client, primary.projectId, primary.projectName, warn, codebasePaths, folderExists, chosenRemote);
+        return { ...chosenContext, items };
+    }
+    let remote = null;
+    try {
+        remote = await resolveCodebaseRemote(client, primary);
+    }
+    catch (err) {
+        warn(`[orchestrator] could not resolve the codebase: ${err.message}`);
+    }
+    /* NO TARGET AND NO SINGLE CODEBASE, so this item cannot decide on its own,
+       and "cannot decide" is two different facts. `resolveCodebaseRemote` folds
+       both into null, so an attached request against a project with TWO codebases
+       was told the project "has no codebase registered": false, and a dead end,
+       because the ambiguity the card knows how to ASK about (Slice 4) never
+       reached it.
+  
+       THE PROJECT RESOLVER IS THE ONE THAT TELLS THEM APART, and it is already
+       the resolution an unattached request gets: none, exactly one, or several
+       with the candidates named. Delegating here rather than restating it is also
+       what keeps a chosen codebase working on this path: `chosenRemote` is
+       verified against the project's own list there, once, for both paths.
+  
+       THE ITEMS SURVIVE THE DELEGATION. They are the prompt's load-bearing
+       context (I6) and the project resolver has none of its own, so a refusal
+       from here still names the work item the request was about. */
+    if (!remote) {
+        const context = await resolveProjectContext(client, primary.projectId, primary.projectName, warn, codebasePaths, folderExists, chosenRemote);
+        return { ...context, items };
+    }
+    const local = codebasePaths()[remote];
+    if (!local) {
+        return {
+            items,
+            checkout: null,
+            gitRemoteUrl: remote,
+            miss: { kind: 'not-located', projectName: primary.projectName, gitRemoteUrl: remote },
+        };
+    }
+    /* THE FOLDER IS CHECKED, NOT TRUSTED. `codebase-paths.json` has no removal
+       path — nothing ever deletes an entry (not `removeCodebase`, not the
+       superseded-machine cleanup) — so a repo the user moved or deleted leaves a
+       stale absolute path behind forever. Spawning into it fails obscurely: the
+       child dies on a chdir the daemon never sees, and the unit is released to
+       retry the same broken path every time. Checking here turns that into the
+       honest refusal the Gherkin asks for. */
+    if (!folderExists(local)) {
+        return {
+            items,
+            checkout: null,
+            gitRemoteUrl: remote,
+            miss: { kind: 'path-missing', projectName: primary.projectName, gitRemoteUrl: remote },
+        };
+    }
+    return { items, checkout: local, gitRemoteUrl: remote, miss: null };
+}
+/**
+ * 18b SLICE 2 — THE CONTEXT FOR A REQUEST WITH NOTHING ATTACHED.
+ *
+ * Its own function rather than a fifth parameter on `resolveWorkContext`,
+ * because the two resolutions genuinely differ and merging them would make both
+ * harder to read: the attached path resolves THROUGH a work item (target first,
+ * then that item's project) and carries the item into the prompt; this path has
+ * only a project id and carries no items at all. Every existing caller and test
+ * fake of `resolveWorkContext` also keeps its arity.
+ *
+ * WHY IT IS A MISS AND NOT AN EMPTY CONTEXT. Before this slice, no attachments
+ * meant `EMPTY_WORK_CONTEXT` with `miss: null` — deliberately, since "nothing
+ * attached" was not a failure to find anything. But the refusal in the tick is
+ * gated on `miss` being non-null, so an unattached code request could not refuse
+ * at any wording: it ran with no working directory at all, which under the
+ * launchd login item is the filesystem root. Now a request that HAS a project
+ * and cannot resolve it to a checkout produces a real miss, and refuses like any
+ * other. A request with no project at all still produces the empty context —
+ * there is nothing to miss.
+ */
+export async function resolveProjectContext(client, projectId, projectName, warn = console.warn, codebasePaths = readCodebasePaths, folderExists = defaultFolderExists, 
+/** 18b SLICE 4 — THE CODEBASE THE USER CHOSE, when they have chosen one.
+ *
+ *  A project with several codebases and no target used to be a dead end: the
+ *  request refused, naming the candidates, and settling it meant leaving the
+ *  panel for project settings. Slice 4 asks on the card instead, and this is
+ *  the answer coming back — the git remote of the ONE codebase this run is
+ *  for. A fan-out across several is N runs, each arriving here with its own.
+ *
+ *  Given one, the ambiguity is gone by construction: it is treated exactly as
+ *  a single-codebase project would be, including the located and path-missing
+ *  checks below, so a chosen codebase that is not on this machine refuses in
+ *  the same words as any other. */
+chosenRemote = null) {
+    /* No project — every row predating Slice 1, and any the composer could not
+       resolve. Unchanged from before this slice: no checkout, and no miss to
+       report, because nothing was ever pointed at. */
+    if (!projectId)
+        return EMPTY_WORK_CONTEXT;
+    /* The name travels with every return below, including the refusals: the
+       prompt names it when the run happens, and the card names it when it does
+       not. */
+    /* The name is for the SENTENCE, not for the resolution. Falling back to the id
+       would put a uuid in front of the user; "its project" is what the existing
+       refusal already says when it has no name. */
+    const named = projectName || 'its project';
+    let remotes = [];
+    try {
+        remotes = await resolveProjectCodebases(client, projectId);
+    }
+    catch (err) {
+        /* Best-effort like every other read in the tick, but NOT silent: a failed
+           read here is reported as "no codebase", which is the same conservative
+           shape the attached path uses. It refuses rather than running nowhere. */
+        warn(`[orchestrator] could not resolve the project's codebases: ${err.message}`);
+        return { items: [], checkout: null, gitRemoteUrl: null, miss: { kind: 'no-codebase', projectName: named }, projectName };
+    }
+    if (remotes.length === 0) {
+        return { items: [], checkout: null, gitRemoteUrl: null, miss: { kind: 'no-codebase', projectName: named }, projectName };
+    }
+    /* 18b SLICE 4 — THE USER ALREADY SAID WHICH, so there is nothing ambiguous
+       left. Verified against the project's own list rather than trusted: the
+       answer arrives from a `selected_options` array the user could in principle
+       have been shown before a codebase was detached, and running in a repository
+       the project no longer has is worse than asking again. An answer that does
+       not match falls through to the ambiguity below and is re-asked. */
+    if (chosenRemote && remotes.includes(chosenRemote)) {
+        return locate(chosenRemote, named, projectName, codebasePaths, folderExists);
+    }
+    /* SEVERAL, AND NOTHING SAYS WHICH. Its own kind, so the card can name the
+       candidates and tell the user to set a target — rather than the old
+       `no-codebase` wording, which told a user with two codebases they had none.
+       Slice 4 turns this into a QUESTION on the card rather than a refusal; the
+       miss is still what carries the candidates to it. */
+    if (remotes.length > 1) {
+        return {
+            items: [],
+            checkout: null,
+            gitRemoteUrl: null,
+            miss: { kind: 'ambiguous-codebase', projectName: named, gitRemoteUrls: remotes },
+            projectName,
+        };
+    }
+    return locate(remotes[0], named, projectName, codebasePaths, folderExists);
+}
+/** ONE REMOTE, RESOLVED TO A CHECKOUT ON THIS MACHINE — or the honest reason it
+ *  cannot be. Extracted in 18b Slice 4 so the project's ONLY codebase and the
+ *  codebase the user CHOSE take exactly the same path: a chosen codebase that is
+ *  not on this machine has to refuse in the same words as any other, and two
+ *  copies of these two checks is how that quietly stops being true. */
+function locate(remote, named, projectName, codebasePaths, folderExists) {
+    const local = codebasePaths()[remote];
+    if (!local) {
+        return { items: [], checkout: null, gitRemoteUrl: remote, miss: { kind: 'not-located', projectName: named, gitRemoteUrl: remote }, projectName };
+    }
+    /* Checked, not trusted — same reason as the attached path: `codebase-paths.json`
+       has no removal path, so a moved or deleted repo leaves a stale absolute path
+       behind forever and spawning into it fails obscurely. */
+    if (!folderExists(local)) {
+        return { items: [], checkout: null, gitRemoteUrl: remote, miss: { kind: 'path-missing', projectName: named, gitRemoteUrl: remote }, projectName };
+    }
+    return { items: [], checkout: local, gitRemoteUrl: remote, miss: null, projectName };
+}
+/** `statSync().isDirectory()` rather than `existsSync`: a path that exists as a
+ *  FILE is not a working directory, and handing one to spawn dies the same
+ *  obscure way a missing one does. */
+function defaultFolderExists(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * WHAT THE WORKER IS WORKING ON, as prompt text — I6.
+ *
+ * Today the prompt carries a bare todo uuid and nothing else: not the item's
+ * title, not its description, not the project, and only the first attachment
+ * even reached the resolution. A worker told "refactor the auth module" with no
+ * idea which product that is has to guess, and it guesses from the repo it was
+ * never placed in.
+ *
+ * NO ABSOLUTE PATH IS EVER PUT IN HERE. The worker learns where it is by BEING
+ * there (the cwd), not by being told a path that would then travel into the
+ * answer column and the cloud. That is the phase's own Gherkin scenario, and it
+ * is why this function takes the items rather than the whole context.
+ */
+export function describeAttachments(items) {
+    if (items.length === 0)
+        return [];
+    const lines = [''];
+    lines.push(items.length === 1
+        ? 'This request is attached to a work item:'
+        : `This request is attached to ${items.length} items:`);
+    for (const item of items) {
+        const kind = item.isIdea ? 'Product idea' : 'Work item';
+        lines.push('');
+        lines.push(`  ${kind}: ${item.name}`);
+        if (item.projectName)
+            lines.push(`  Project: ${item.projectName}`);
+        lines.push(`  Id: ${item.id}`);
+        if (item.description.trim()) {
+            /* THE DESCRIPTION IS INDENTED AS A BLOCK, not flattened onto one line: it
+               is authored prose that can carry its own paragraphs and lists, and
+               collapsing it would destroy the structure the user wrote. */
+            lines.push('  Description:');
+            for (const line of item.description.trim().split('\n'))
+                lines.push(`    ${line}`);
+        }
+    }
+    return lines;
+}
+/** The line that tells a worker it is ALREADY in the repository — so it does
+ *  not go looking for one, and does not wander outside it. Empty when there is
+ *  no checkout, because claiming a directory the worker is not in would be
+ *  worse than saying nothing. */
+export function describeCheckout(context) {
+    if (!context.checkout)
+        return [];
+    /* 18b SLICE 2 — IT SAYS WHOSE REPOSITORY IT IS, TRUTHFULLY. This used to be
+       hardcoded to "this work item's repository", which is false for a request
+       that resolved its checkout from its PROJECT and has no work item at all —
+       the agent would be told to look for an item it was never given. The two
+       cases now say what is actually true of each. */
+    const whose = context.items.length > 0 ? 'this work item\'s' : 'this project\'s';
+    return [
+        '',
+        `You are ALREADY INSIDE ${whose} repository — your working directory is its`,
+        'checkout on this machine. Use relative paths from here. Do not search the filesystem',
+        'for the project, do not clone it, and do not modify anything outside this directory.',
+    ];
+}
+/**
+ * 18b SLICE 2 — THE PROJECT A REQUEST BELONGS TO, IN THE PROMPT.
+ *
+ * `describeAttachments` returns nothing when there are no attachments, so an
+ * unattached request's prompt named no project even once Slice 1 had recorded
+ * one. Proven, not assumed: asked "in one sentence, say what this project is
+ * for" against TalentTrack, the subagent replied that the request "came through
+ * with no project attached" and listed every project in the workspace.
+ *
+ * NAME ONLY, NEVER THE PATH. The path invariant is absolute here: the worker
+ * learns where it is by BEING there (`describeCheckout`), and no absolute path
+ * is ever put in a prompt or in a database column (AGENTS.md).
+ */
+export function describeProject(projectName, hasItems) {
+    /* An attached request already names its project per item, and repeating it
+       would be two answers to one question when the item's project and the
+       request's disagree. The item wins there — it is the more specific fact. */
+    if (hasItems || !projectName)
+        return [];
+    return ['', `This request belongs to the project: ${projectName}`];
+}
+/**
+ * 18b SLICE 6b — WHICH EPIC OR SPRINT THE REQUEST IS ABOUT.
+ *
+ * Slice 6 let the user attach one and resolved its project so the run had a
+ * directory, but the prompt never named it. Asked to "summarise this epic's
+ * sprints", the agent had no way to know which epic "this" meant, and its only
+ * honest move was to list every epic in the project or ask.
+ *
+ * THE IDENTITY, NOT THE CONTENTS. This says which epic and gives its id; it does
+ * NOT summarise the sprints or paste the backlog. Two reasons, and the second is
+ * the load-bearing one:
+ *
+ *   1. The tools already do it better. `list_structure` returns the project's
+ *      epics and sprints; `list_tasks` returns the backlog with each row's epic
+ *      and sprint, in order. Both are already granted to every worker.
+ *   2. A PRE-BAKED SUMMARY GOES STALE THE MOMENT IT IS WRITTEN. The prompt is
+ *      built when the run is dispatched; the board can change between then and
+ *      the answer. An id the agent resolves for itself is correct when it is
+ *      read. This is the same argument the links table makes for storing a
+ *      reference rather than a copied name.
+ *
+ * THE ID IS GIVEN because `list_structure` returns every epic in the project and
+ * the agent has to know which row is the one it was pointed at. Names are not
+ * unique — "Search 1" is a plausible name for both a sprint and a work item
+ * inside it, which is exactly why Slice 6 put the kind on the chip.
+ */
+export function describeStructure(structure) {
+    if (!structure)
+        return [];
+    const kind = structure.kind === 'epic' ? 'epic' : 'sprint';
+    const named = structure.name.trim();
+    const lines = [
+        '',
+        named
+            ? `This request is about the ${kind} "${named}" (id: ${structure.id}).`
+            /* An unnamed row is a real case — `name` is nullable on neither table in
+               practice, but the read coalesces to '' rather than throwing, and a
+               prompt reading `the epic ""` would be worse than one that just gives the
+               id. */
+            : `This request is about a ${kind} (id: ${structure.id}).`,
+    ];
+    lines.push(kind === 'epic'
+        ? 'Read what is under it with list_structure (the project\'s epics and sprints) and'
+        : 'Read what is in it with list_tasks, whose rows each name their epic and sprint.');
+    if (kind === 'epic') {
+        lines.push('list_tasks, whose rows each name their epic and sprint. Match on the id above.');
+    }
+    else {
+        lines.push('Match on the id above; do not answer about another sprint\'s work.');
+    }
+    return lines;
+}
+/**
+ * 18d SLICE 1 — WHAT THE USER SELECTED, READ BACK FOR THE PROMPT.
+ *
+ * The drawer's whole promise is that a selection BINDS: the skill the user
+ * pointed at is the one that gets read, not one a discovery step chose. That
+ * promise lives or dies here, because the prompt is the only channel to a
+ * headless `claude -p` run.
+ *
+ * ONE READ FOR THE LINKS, THEN ONE PER KIND ACTUALLY PRESENT. `skills`,
+ * `credentials` and `cliv2_workflows` are read through the user's own RLS,
+ * exactly as `tasks` and `epics` are read above — AGENTS.md permits v2 to READ
+ * shared product data; it is v2's writes that must stay in `cliv2_*`.
+ *
+ * NAMES, NEVER VALUES. The `credentials` select is `id, name` and nothing else.
+ * A secret has no business in a prompt, and the prompt travels into the answer
+ * column: story 2's pass condition is precisely that the value appears in no
+ * answer, no progress line and no record.
+ *
+ * BEST-EFFORT, LIKE EVERY OTHER READ IN THE TICK. A failure yields `[]` rather
+ * than costing the user the request. The cost of the empty case is that the run
+ * falls back to discovery, which is the behaviour of every send that selected
+ * nothing — degraded, not broken.
+ *
+ * IN LINK ORDER, so "the first skill" means the first one picked.
+ */
+export async function readSelectedTools(client, todoId) {
+    try {
+        const { data: links, error } = await client
+            .from('cliv2_loose_todo_links')
+            .select('work_item_id, kind, created_at')
+            .eq('todo_id', todoId)
+            .in('kind', ['skill', 'credential', 'workflow'])
+            .order('created_at', { ascending: true });
+        if (error)
+            throw new Error(error.message);
+        const wanted = (links ?? [])
+            .map((row) => ({
+            id: row.work_item_id,
+            kind: linkKind(row),
+        }))
+            .filter((row) => (row.kind === 'skill' || row.kind === 'credential' || row.kind === 'workflow') &&
+            typeof row.id === 'string' &&
+            row.id !== '');
+        if (wanted.length === 0)
+            return [];
+        const idsOf = (kind) => wanted.filter((row) => row.kind === kind).map((row) => row.id);
+        /* Resolved name by name into one map keyed `kind:id`, because the three id
+           keyspaces are independent and a skill and a workflow could share a uuid. */
+        const named = new Map();
+        const skillIds = idsOf('skill');
+        if (skillIds.length > 0) {
+            /* The org comes through `skill_bundles`, because `skills` has no `org_id`
+               of its own — the same hop `loadSkills` makes in the web app. It is
+               carried only so the prompt can pass `get_skill`'s optional `org_id`,
+               which is what disambiguates a skill name held by two organizations.
+      
+               `deleted_at is null` MATCHES WHAT `get_skill` WILL DO. Skills are
+               archive-not-remove, so a removed skill's row survives; without this
+               filter the prompt would bind the run to a skill and `get_skill` would
+               then answer "no skill named X", leaving the worker between an
+               instruction it must follow and a tool that refuses. Dropped here
+               instead, which is the documented fallback: discovery. */
+            const { data, error } = await client
+                .from('skills')
+                .select('id, name, skill_bundles(org_id)')
+                .in('id', skillIds)
+                .is('deleted_at', null);
+            if (error)
+                throw new Error(error.message);
+            for (const row of data ?? []) {
+                const skill = row;
+                const bundle = Array.isArray(skill.skill_bundles) ? skill.skill_bundles[0] : skill.skill_bundles;
+                named.set(`skill:${skill.id}`, { name: skill.name, orgId: bundle?.org_id ?? null });
+            }
+        }
+        const credentialIds = idsOf('credential');
+        if (credentialIds.length > 0) {
+            /* `id, name` ONLY. Not the secret (which this client cannot read anyway),
+               not `username`, not `kind`. */
+            const { data, error } = await client.from('credentials').select('id, name').in('id', credentialIds);
+            if (error)
+                throw new Error(error.message);
+            for (const row of data ?? []) {
+                const credential = row;
+                named.set(`credential:${credential.id}`, { name: credential.name, orgId: null });
+            }
+        }
+        const workflowIds = idsOf('workflow');
+        if (workflowIds.length > 0) {
+            /* `archived_at is null` MATCHES `start_workflow`, which refuses an
+               archived workflow. Binding the run to one the tool will not start is
+               the same trap the skills read above avoids. */
+            const { data, error } = await client
+                .from('cliv2_workflows')
+                .select('id, name, org_id')
+                .in('id', workflowIds)
+                .is('archived_at', null);
+            if (error)
+                throw new Error(error.message);
+            for (const row of data ?? []) {
+                const workflow = row;
+                named.set(`workflow:${workflow.id}`, { name: workflow.name, orgId: workflow.org_id ?? null });
+            }
+        }
+        /* A selection whose row no longer resolves is DROPPED rather than named as
+           an id, matching what an attachment pointing at a deleted task does. */
+        return wanted
+            .map((row) => {
+            const hit = named.get(`${row.kind}:${row.id}`);
+            return hit ? { kind: row.kind, id: row.id, name: hit.name, orgId: hit.orgId } : null;
+        })
+            .filter((tool) => tool !== null);
+    }
+    catch {
+        return [];
+    }
+}
+/** A name going inside a double-quoted JSON-ish literal in the prompt. Skill,
+ *  credential and workflow names are user-authored on the product's own pages,
+ *  so one containing a quote or a backslash would otherwise print a literal the
+ *  agent cannot parse. */
+function quoted(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+/**
+ * 18d SLICE 1 — THE SELECTION BINDS, AND THIS IS WHERE IT SAYS SO.
+ *
+ * NOTHING SELECTED PRODUCES NOTHING. The guard returns `[]`, so a send that
+ * selected nothing yields a prompt byte-identical to today's and the general
+ * "list_skills, then get_skill" guidance in `describeToolSurface` still fires.
+ * That is how "an empty selection changes nothing" is guaranteed structurally
+ * rather than by test: discovery is not something this block turns off, it is
+ * something this block does not mention.
+ *
+ * NAMES AND IDS BOTH. `get_skill` and `get_credential` take a NAME, which is
+ * what makes them usable at all; but credential names are unique only per
+ * (org, creator) — `credentials_owner_name_uq` — so a user who can reach their
+ * own token and one shared to them under the same name gets a refusal from
+ * `get_credential`, which accepts no id and no org to disambiguate with. The id
+ * is printed anyway, for the agent's own reading and so the refusal is
+ * intelligible. That limit is Slice 3's to close, not this slice's.
+ *
+ * A SEPARATE FUNCTION, NOT LINES INSIDE `describeToolSurface`, whose character
+ * budget is pinned by a test. This block is conditional; that one is not.
+ */
+export function describeSelectedTools(selected) {
+    if (!selected || selected.length === 0)
+        return [];
+    const lines = [
+        '',
+        "The user SELECTED these in the panel's tool drawer. Use exactly these; do not",
+        'substitute one for another and do not run a discovery step to re-choose them.',
+    ];
+    for (const tool of selected) {
+        if (tool.kind === 'skill') {
+            const args = tool.orgId
+                ? `{ name: ${quoted(tool.name)}, org_id: ${quoted(tool.orgId)} }`
+                : `{ name: ${quoted(tool.name)} }`;
+            lines.push(`  Skill: ${tool.name} — get_skill(${args}), then FOLLOW it for the rest of this run.`);
+        }
+        else if (tool.kind === 'credential') {
+            lines.push(`  Credential: ${tool.name} (id: ${tool.id}) — read its value with ` +
+                `get_credential({ name: ${quoted(tool.name)} }) when the work needs it.`);
+        }
+        else {
+            /* The id is printed because `start_workflow` takes ids, not names. The
+               work item is described rather than printed as a bare `work_item_id`
+               key: this function does not know which item is attached, and a
+               half-written object literal is worse than a sentence. */
+            lines.push(`  Workflow: ${tool.name} — start it on the work item this request is ` +
+                `attached to, with start_workflow({ workflow_id: ${quoted(tool.id)}, work_item_id: ... }).`);
+        }
+    }
+    return lines;
+}
+/**
+ * DOES THIS INSTRUCTION ACTUALLY NEED THE CODE?
+ *
+ * The unhappy path must refuse a codebase instruction whose checkout is missing.
+ * It must NOT refuse "what is this work item about?", which is answerable from
+ * the product alone and is the panel's most common use — turning that into a
+ * "locate your codebase" dead end would be a worse regression than the bug.
+ *
+ * SO THE DEFAULT IS TO RUN, and this is the deliberate direction of the error.
+ * A wrong "needs code" STOPS work the user could have had; a wrong "does not"
+ * costs a run that reports it could not find the files, which is recoverable and
+ * self-explanatory. Only a clear signal flips it.
+ *
+ * A KEYWORD MATCH, AND ITS CEILING IS STATED. This cannot classify intent — it
+ * is a word list, and `checkDirection`'s substring weakness in this same product
+ * is the standing lesson about pretending otherwise. It catches the verbs that
+ * mean "change the code" and nothing subtler. What makes that acceptable here is
+ * that the ONLY consequence of a miss is which of two honest outcomes the user
+ * gets: a refusal naming the fix, or a run that finds nothing to edit and says
+ * so. Neither writes anything, and neither is silent.
+ *
+ * ponytail: a word list, not a classifier. Phase 7 introduces real work typing
+ * (I23) — when a request carries a kind, this should read that instead.
+ */
+const CODE_VERBS = [
+    'refactor', 'implement', 'fix', 'debug', 'edit', 'rename', 'delete',
+    'add a test', 'write a test', 'add tests', 'run the test', 'run tests',
+    'commit', 'build', 'compile', 'install', 'upgrade', 'migrate',
+    'readme', 'codebase', 'repository', 'the repo', 'this repo',
+];
+export function instructionNeedsCheckout(instruction) {
+    const text = instruction.toLowerCase();
+    return CODE_VERBS.some((verb) => text.includes(verb));
+}
+/* ═══ !Cleanup PHASE 2b — SCOPE GATES BUILDING, NOT THINKING. ═══
+ *
+ * THE USER'S RULE, verbatim: "Scope should be a gate to BUILDING, not a gate to
+ * performing research and planning."
+ *
+ * THE DEADLOCK THIS BREAKS, found by trying to walk Phase 2 as a user rather
+ * than by reading the code. `orchestratorTick` asked `cliv2_scope_is_approved`
+ * before dispatching ANYTHING, so a work item with no approved scope refused
+ * research, planning, spec.md, prd.md, a mock, and even a plain question about
+ * itself. Writing the scope document is exactly how a user OBTAINS a scope to
+ * approve — so the gate blocked the only work that could unblock it, and the
+ * card's suggested next step ("Open the work item to draft its scope") named a
+ * control that does not exist. The walk could only proceed via the database.
+ *
+ * THE PRODUCT ALREADY AGREED, which is what makes this narrow: `create_artifact`
+ * is NOT scope-gated in mcp.ts. Only `create_stage`, `create_step` and
+ * `update_step` are. An agent that gets to run may already write documents and
+ * mocks; the one surface contradicting that was the daemon's blanket gate. This
+ * changes the daemon and leaves 16g's three MCP call sites exactly as shipped.
+ *
+ * SO THE QUESTION IS "IS THIS BUILDING?", NOT "IS THIS APPROVED?".
+ *
+ * THE DEFAULT IS **NOT** BUILDING, and the direction of that error is chosen,
+ * not incidental. Guessing "building" wrongly re-creates the deadlock this
+ * phase exists to remove, and the user is stuck again. Guessing "planning"
+ * wrongly dispatches a worker that is TOLD not to edit the repository (see
+ * `describePlanningPosture`) against an item whose scope nobody approved — and
+ * the execution-writing tools are still gated in mcp.ts regardless. One error
+ * is a dead end; the other is a run that writes a document. They are not
+ * symmetric, so the default follows the recoverable one.
+ *
+ * ponytail: a word list, not a classifier — same ceiling and same upgrade path
+ * as `instructionNeedsCheckout`. Phase 7's work typing (I23) is the real answer;
+ * when a request carries a kind, this reads that instead of guessing.
+ */
+const BUILD_VERBS = [
+    'implement', 'build', 'code ', 'write the code', 'refactor', 'fix',
+    'add a test', 'write a test', 'add tests', 'make it work',
+    'ship it', 'deploy', 'migrate', 'rename', 'delete',
+    /* CHANGING A FILE IS BUILDING, even when the change is small and even when
+       the thing being written is prose. Phase 2's own happy path — "add a comment
+       at the top of the README" — matched none of the verbs above, so it fell
+       through to planning and the worker would have been told it must not edit
+       the repository. A README edit is an edit. */
+    'edit', 'update the', 'change the', 'add a comment', 'remove the',
+    'commit', 'readme',
+];
+/** Words that mean THINKING, and that beat a build verb when both appear.
+ *  "write a spec for the fix" is planning about a fix, not a fix — and without
+ *  this the bare `fix` would send it down the gated path. */
+const PLANNING_VERBS = [
+    'spec', 'prd', 'research', 'investigate', 'explore', 'analyse',
+    'analyze', 'wireframe', 'diagram', 'summarise', 'summarize',
+    'recommend', 'propose', 'estimate',
+];
+/* A QUESTION IS PLANNING, BUT ONLY WHEN IT IS ACTUALLY ASKING — anchored at the
+   START, not matched anywhere in the sentence.
+   CAUGHT BY RUNNING THE CLASSIFIER OVER PHASE 2'S OWN HAPPY PATH, not by a unit
+   test: "add a comment at the top of the README explaining what this repo is"
+   was classified PLANNING, because the unanchored `what ` and `explain` matched
+   words describing the COMMENT'S CONTENT. The consequence was not cosmetic — the
+   worker would have been told it must not edit the repository, so the phase's
+   own headline scenario could never have completed. Interrogatives only mean a
+   question when they open the sentence; anywhere else they are ordinary words. */
+const QUESTION_OPENERS = /^\s*(what|why|how|which|who|when|where|is|are|does|do|can|should|could|would|explain|tell me|describe|summar)/i;
+/* Words that name a DOCUMENT to produce. Unlike the interrogatives these are
+   safe anywhere, but `plan`, `design`, `mock`, `scope` and `document` are only
+   planning when something is being MADE — "implement the design" and "delete the
+   mock data" are builds that happen to contain them, which is why they need a
+   producing verb rather than standing alone. */
+const PRODUCE_VERBS = /\b(write|draft|create|produce|make|prepare|put together|come up with)\b[^.]{0,40}\b(plan|design|mock|scope|document|doc|spec|prd|proposal|outline|brief)/i;
+/* `plan` and `design` used as VERBS — "plan the migration", "design how search
+   works". Separate from the pattern above because there is no producing verb to
+   anchor on: the word IS the instruction. Still narrow enough that "implement
+   the design" and "delete the mock data" stay builds, because those have the
+   word in object position rather than leading a clause. */
+const PLAN_AS_VERB = /\b(plan|design|scope|spec)\s+(the|this|out|how|what|a\b|an\b|for\b)/i;
+/**
+ * DOES THIS INSTRUCTION BUILD SOMETHING? Only a true answer needs approved scope.
+ *
+ * Planning wins ties deliberately — see the block comment above.
+ */
+export function instructionIsBuilding(instruction) {
+    const text = instruction.toLowerCase();
+    if (QUESTION_OPENERS.test(instruction))
+        return false;
+    if (PRODUCE_VERBS.test(instruction))
+        return false;
+    if (PLAN_AS_VERB.test(instruction))
+        return false;
+    if (PLANNING_VERBS.some((verb) => text.includes(verb)))
+        return false;
+    return BUILD_VERBS.some((verb) => text.includes(verb));
+}
+/**
+ * WHAT A PLANNING RUN IS ALLOWED TO DO — the other half of opening the gate.
+ *
+ * Dispatching planning against an unapproved work item is only safe if the
+ * worker KNOWS it is planning. Without this it receives an instruction, finds
+ * itself inside a real checkout (Phase 2), and builds — which is precisely what
+ * the scope gate exists to prevent, arrived at by the back door.
+ *
+ * NOT STAGES AND STEPS (user ruling, 2026-08-06). Stages and steps "hold what is
+ * true" and are stamped with the approved scope revision (16g Slice 4), so
+ * recording planning there would assert execution against a contract nobody
+ * approved. The live view is the right surface: present tense, and referenced by
+ * nothing. It is no longer EPHEMERAL — 18c Slice 4 keeps the final frame on the
+ * work item after the run ends — but that does not make it a record, which is
+ * the property this ruling actually turned on: nothing links to a frame, and no
+ * agent can read one back.
+ *
+ * THE LIVE VIEW IS NAMED ONLY WHEN IT IS REACHABLE. `draw_live_view` is
+ * session-anchored and refuses without `begin_work`, which a panel worker
+ * structurally cannot call (I12, Phase 4). Telling a worker to call a tool that
+ * will refuse it teaches it the product is broken, so the line is conditional
+ * and Phase 4 turns it on.
+ */
+export function describePlanningPosture(canDrawLiveView = false) {
+    return [
+        '',
+        'THIS IS PLANNING OR RESEARCH, NOT BUILDING. This work item has no approved scope',
+        'yet, which is exactly why you are being asked to think rather than to build.',
+        '',
+        'You MAY: read the codebase, research, and produce documents and pictures —',
+        'a spec, a PRD, a plan, a mock, a diagram — with create_artifact on the work item.',
+        'You MUST NOT: edit, create or delete any file in the repository, and must not',
+        'run anything that changes it. If the answer is code, WRITE IT INTO A DOCUMENT',
+        'rather than into the repo.',
+        ...(canDrawLiveView
+            ? ['', 'Use draw_live_view to show what you are working through as you go.']
+            : []),
+    ];
+}
+/**
+ * 18c SLICE 9: SAY WHAT YOU ARE ABOUT TO CHANGE, BEFORE YOU CHANGE IT.
+ *
+ * Spec: .implementations/18-orchestrator/18c-you-watch-the-work-happen/ux.md
+ * § "Slice 9. A run says what it is about to change" and § Story 8.
+ *
+ * THIS IS THE WRITE HALF OF THE PROBE, and it is the whole reason the slice
+ * exists. `reserve_work_paths` and `release_work_paths` have been registered
+ * since the MCP server shipped, carrying conflict detection, read/write modes
+ * and a read-to-write upgrade, and `cliv2_work_reservations` has had ZERO
+ * ROWS, EVER, because no prompt ever told an agent to declare. The coordinator's
+ * read half arrived later and has therefore never had anything to read. Nothing
+ * about the tool needed building; this sentence did.
+ *
+ * IT IS THE RISKIEST PREMISE IN THE FEATURE AND IT IS HERE TO BE ALLOWED TO
+ * FAIL. Whether an agent will reliably declare BEFORE it edits is what four
+ * later folders depend on, and 18g at position seven is an expensive place to
+ * find out. So this asks plainly, once, in the run's own terms, and the tester
+ * checks the result against what actually changed in the checkout. Two passes
+ * out of three is a failure. It is deliberately NOT reinforced with a gate, a
+ * retry or a refusal: a probe that coerces the behaviour cannot measure it.
+ *
+ * ─── WHY IT IS ITS OWN BLOCK AND NOT A LINE IN `describeToolSurface` ────────
+ *
+ * Three reasons, and the third is the load-bearing one.
+ *
+ *   1. IT IS CONDITIONAL ON HAVING A REPOSITORY. A run with no checkout has
+ *      nothing to declare, and naming a tool that has no meaningful argument to
+ *      pass is the "named a tool that will refuse it" mistake `describeToolSurface`'s
+ *      own header is about.
+ *   2. IT IS CONDITIONAL ON BEING ALLOWED TO WRITE. A planning run is told in
+ *      the strongest terms not to touch a file (`describePlanningPosture`), so
+ *      telling it to declare the files it is about to change would be two
+ *      instructions that contradict each other, and the agent gets to pick.
+ *   3. THE TOOL SURFACE HAS A HARD CHARACTER BUDGET (test/tool-surface.test.mjs,
+ *      "R2: the guidance stays short enough to be read"). That cap exists so
+ *      growing the always-on guidance is a decision somebody makes rather than a
+ *      drift, and it has been raised once, deliberately, with the reasoning
+ *      recorded. This text is not always-on, so spending the budget on it would
+ *      charge every run for something only a building run in a checkout reads.
+ *
+ * ─── WHAT IT SAYS, AND WHY EACH PART IS THERE ───────────────────────────────
+ *
+ * BEFORE, STATED AS THE POINT RATHER THAN AS AN ORDERING DETAIL. The scenario is
+ * "it shows them before anything in the checkout has changed". An agent told to
+ * "reserve the paths you edit" reasonably reserves them as it goes, which
+ * produces a declaration that is a log rather than a declaration and proves
+ * nothing about the premise.
+ *
+ * THE ADDRESS IS GIVEN, NOT ASKED FOR. The run is standing in the checkout and
+ * could read its own remote, but the spelling it would find is the checkout's,
+ * which is exactly the mismatch gap 14 is about. Handing it the canonical value
+ * the product already resolved removes a guess. The tool canonicalizes either
+ * way now, so this is belt and braces rather than the fix.
+ *
+ * A REMOTE URL IS NOT A PATH, so this does not touch the invariant. It is a
+ * shareable, path-free identifier: the same value `checkoutMissAnswer` already
+ * prints to the user and the same one the cloud column stores. No absolute local
+ * path appears here, and the paths the agent declares BACK are repo-relative:
+ * the database CHECK refuses an absolute one outright.
+ *
+ * DECLARING AND LEAVING IT ALONE IS EXPLICITLY FINE. Story 8: "a file it named
+ * but left alone is not a failure". Without that sentence an agent under-declares
+ * to avoid being wrong, which biases the very measurement being taken.
+ *
+ * RELEASING IS MENTIONED AND NOT LEANED ON. Gap 15 is fixed in the product
+ * (mcp.ts `releaseSessionReservations`), so the run finishing releases whatever
+ * it declared whether or not the agent remembers. The line is here because an
+ * agent that does release promptly frees a path earlier than its session end
+ * would, and because a tool nobody is told about is a tool nobody calls, which
+ * is the entire lesson this slice is built on.
+ *
+ * NOTHING HERE SEQUENCES, WAITS, ISOLATES, OFFERS OR MERGES. Story 8 declares,
+ * matches and releases and stops. A conflict comes back as information; what a
+ * collision should OFFER the user is 18g's and must not be implied here. The
+ * text says so, because an agent told about conflicts and not told what to do
+ * with one will invent a policy.
+ */
+export function describeDeclarationDuty(gitRemoteUrl) {
+    /* NO REPOSITORY, NOTHING TO DECLARE. Silence rather than a hedged sentence:
+       the run has no codebase key to pass and no files to name. */
+    if (!gitRemoteUrl)
+        return [];
+    return [
+        '',
+        'BEFORE YOU CHANGE ANY FILE, SAY WHICH FILES YOU ARE ABOUT TO CHANGE. Work out which',
+        'ones the job needs, then call it ONCE, before the first edit:',
+        `  reserve_work_paths({ git_remote_url: '${gitRemoteUrl}', paths: [...] })`,
+        'Paths are relative to the repository root: never absolute, and never a folder on',
+        'this machine. The user sees what you declared on this run\'s card while you work, so',
+        'declaring afterwards defeats the point of it.',
+        '',
+        'Naming a file and then leaving it alone is fine. Changing one you did not name is',
+        'not, so if the work turns out to need a file you missed, declare that one too before',
+        'you touch it. If the call reports a conflict, that is information and nothing more:',
+        'it does not block you, and you decide what to do about it.',
+        '',
+        'Call release_work_paths with the ids you were given once you have finished with',
+        'those files.',
+    ];
+}
+/* ═══ !Cleanup PHASE 3 — THE WORKER KNOWS THE PRODUCT EXISTS. ═══
+ *
+ * THE GAP (I7). The worker is handed 50 tools as NAMES ONLY. Every word of
+ * teaching this product has written — 42,192 characters across those 50
+ * descriptions, plus 9,362 more in per-parameter `.describe()` strings — arrives
+ * only once a tool has already been chosen, which is exactly the moment it is no
+ * longer needed.
+ *
+ * THE FIGURE IS MEASURED FROM THE BUILT SERVER, not from the source, and that
+ * distinction cost a correction. Counting the string literals in mcp.ts gives
+ * ~26,500, because most descriptions are written as several `+`-concatenated
+ * literals and a source-level count sees only the fragments. What an agent
+ * actually receives is the registered string: 42,192. The plan's number was
+ * right and is left alone.
+ *
+ * A worker that never looks never learns, so the tools that decide the shape of
+ * a run —
+ * skills, credentials, and the read-before-you-write ones — are named HERE, in
+ * the prompt, in the order they are called.
+ *
+ * ONLY WHAT IT CAN ACTUALLY CALL. Verified against mcp.ts rather than assumed,
+ * because naming a tool that will refuse teaches the worker the product is
+ * broken — the standing lesson from `describePlanningPosture`, and the reason
+ * this function takes a flag rather than printing one list.
+ *
+ * A panel worker has NO SESSION and structurally cannot open one: `begin_work`
+ * needs a work item and `cliv2_agent_sessions.task_id` is NOT NULL (I12,
+ * Phase 4). What it may call:
+ *
+ *   read      list_tasks, get_task, get_project_context, list_steps,
+ *             list_skills, get_skill, list_credentials, get_credential
+ *   write     create_artifact (takes task_id), ask_question (takes todo_id),
+ *             report_blocked, and create_task / create_epic / create_sprint /
+ *             reorder_backlog ONLY when directed
+ *
+ * and what refuses it outright: begin_work, draw_live_view, present_mocks,
+ * present_wireframes, create_stage, create_step, update_step, add_comment,
+ * record_user_input, record_context_exploration, and every undirected gated
+ * write.
+ *
+ * THE TRAP IN THE PHASE'S OWN SECOND HAPPY PATH, found by reading the gate
+ * rather than the plan. "It offers, the user approves in the Inbox, and one work
+ * item appears" cannot happen through the permission gate: `runDirected` falls
+ * back to `runGated`, `runGated` calls `checkGrant`, and `checkGrant` with a
+ * null session returns "call begin_work first" WITHOUT raising an Ask. For a
+ * panel worker the undirected path is a dead end, not a consent round. The only
+ * route to the experience the plan describes is `ask_question({ todo_id })`,
+ * which is anchored on the request rather than on a session — so that is what
+ * this text says, and it is why it says it in that order.
+ */
+/**
+ * THE TOOLS THAT DECIDE THE SHAPE OF A RUN, by role and in call order — I7,
+ * I9, I10.
+ *
+ * TEN, NOT FIFTY. R2's standing objection to this phase is that guidance long
+ * enough to be complete is guidance nobody reads, and I29 says the same about
+ * the descriptions. So this names the ones a worker cannot do its job without
+ * and lets the other forty be discovered: the read-first pair, the two that
+ * make a stored process reachable, the two that make a stored secret reachable,
+ * the one route to the user, and the two ways to leave something behind.
+ *
+ * THE INFORMATION-VERSUS-WORK RULE IS FIRST (I9), because it is the rule that
+ * decides whether any of the rest applies. Nothing anywhere in the product
+ * states it today and both entry points push the other way: the server's
+ * standing instructions say to use a tool for everything, and the dispatch
+ * prompt says to do the work with its tools. A worker that opens a work item
+ * for every passing question fills the board with noise the user must clean up.
+ */
+export function describeToolSurface(canUseSession = false, 
+/* CAN IT REACH THE USER AT ALL? `ask_question` is anchored on the request id,
+   and a prompt built without one (every caller before 16d, and the tests that
+   pin that path) has no id to put in the call. Naming the tool anyway would
+   tell the worker to call something with an argument it was never given —
+   the same "named a tool that will refuse it" mistake this function's header
+   is about, one level down. The orchestrator passes true whenever it has a
+   todo id, which on the real dispatch path is always. */
+canAsk = true) {
+    return [
+        '',
+        'CTRL+SPC holds this user\'s real projects, work items and artifacts. FIRST, DECIDE',
+        'WHICH KIND OF REQUEST THIS IS — get it wrong and everything below is wrong too:',
+        '',
+        '  A QUESTION IS ANSWERED, NOT RECORDED. If the user asked what something is, how it',
+        '  works, where it lives or why it was done that way, find out and say so. Create',
+        '  NOTHING: no work item, no artifact, no epic, no sprint, no product idea, no',
+        '  comment. If nothing about the codebase or the schema needs to change, nothing',
+        '  needs to be filed either — an unwanted work item is worse than no answer, because',
+        '  the user has to clean it up.',
+        '',
+        '  WORK IS DIFFERENT. If they asked you to change, build, fix or produce something,',
+        '  do it — and record it as described below.',
+        '',
+        ...(canAsk
+            ? [
+                '  WHEN IT IS WORK BUT THEY DID NOT ASK YOU TO CREATE ANYTHING, OFFER FIRST. Say',
+                '  what you would create and ask, using ask_question with this request\'s id. Never',
+                '  create one silently, and never several on your own initiative.',
+            ]
+            : [
+                '  WHEN IT IS WORK BUT THEY DID NOT ASK YOU TO CREATE ANYTHING, DO NOT CREATE IT.',
+                '  Say in your answer what you would create and why, and let the user decide. Never',
+                '  create one silently, and never several on your own initiative.',
+            ]),
+        '',
+        'BEFORE YOU CREATE ANYTHING, LOOK FOR IT with list_tasks (get_task for detail). If a',
+        'work item already covers this, name it and use it — a near-duplicate is refused,',
+        'and that is the right refusal.',
+        '',
+        'THE PRODUCT MAY ALREADY KNOW HOW TO DO THIS. Before improvising a method:',
+        '  - list_skills, then get_skill — the team\'s own written processes. A skill is a',
+        '    document TO FOLLOW, not reference material to summarise. If one matches the work,',
+        '    read it and follow it for the rest of the run.',
+        /* ═══ 18d SLICE 4 — THIS LINE CONTRADICTED THE SHIPPED INSTRUCTION. ═══
+    
+           Slice 3 rewrote CREDENTIAL_INSTRUCTION (mcp.ts) to lead with permission,
+           because the old wording made claude fetch a credential and then refuse to
+           use it across three real runs, ending "Blocked", while codex read the same
+           words and made the call. That rewrite explicitly permits "a config file on
+           this machine".
+    
+           THIS LINE STILL CARRIED THE OLD RULE, and it arrives FIRST — at the top of
+           every worker's prompt, hundreds of turns before the tool result. So the
+           agent's first and most recent word on the subject disagreed, and the
+           posture story 3 needs (be refused, then do NOT route around it) is exactly
+           where a contradictory instruction reproduces the "Blocked" ending.
+    
+           NET-NEUTRAL BY CONSTRUCTION. tool-surface.test.mjs caps this guidance at
+           3440 chars with 16 to spare and three raise arguments already rejected on
+           the record, so the replacement is measured, not argued. */
+        '  - list_credentials, then get_credential — secrets the user already stored. If the',
+        '    work needs one, FETCH IT and USE it, never ask for it. Keep the VALUE out of',
+        '    your answer, a commit or an artifact; name the credential instead.',
+        '  - get_project_context — the instructions, architecture, design and conventions the',
+        '    team keeps here instead of in a repo.',
+        '',
+        ...(canAsk
+            ? [
+                'TO REACH THE USER there is one route: ask_question. Not a terminal prompt, which',
+                'nobody is watching, and not a question in your answer, which nobody can answer.',
+                '',
+            ]
+            : []),
+        'TO LEAVE SOMETHING BEHIND: create_artifact for anything that outlives the run — a',
+        'spec, a plan, a document, a mock. Never a loose file, and never only in your answer.',
+        /* !Cleanup PHASE 7 SLICE 1b — EVERY RUN OPENS A SESSION NOW.
+           USER RULING, 2026-08-06: "Panel agents absolutely must be able to do
+           anything another agent can do."
+    
+           WHAT THIS REPLACED, because the reversal matters: Phase 4 could not widen
+           the session anchor, so a panel worker had no session and the whole block
+           below was gated off. It compensated by having the worker ASK for a work
+           item — right when the work deserves one, wrong as the only route, because
+           it made "can this agent record a step?" depend on whether the user agreed
+           to put a row on their board. Slice 1b made `cliv2_agent_sessions.task_id`
+           nullable and added `todo_id`, so a panel run opens a session on its
+           REQUEST and the tools stop refusing it.
+    
+           The ask-for-a-work-item route (Phase 4) is KEPT below, because it is still
+           correct for its own reason: work that genuinely has to be built deserves a
+           visible item. It is no longer the price of using the tools. */
+        '',
+        /* !Cleanup Phase 7 Slice 1b: the ANCHORS NAMED depend on what this run
+           actually has. `todo_id` is only mentionable when there IS a request id —
+           16d's rule, and it is right: a worker told to pass an id it was never
+           given has a dead instruction, which is I8 one level down. */
+        ...(canAsk
+            ? [
+                'OPEN A SESSION FIRST: begin_work with task_id if there is a work item above, or',
+                'todo_id (this request) if not. It attributes what you produce to this run, and most',
+                'tools refuse without it. end_work when you finish.',
+            ]
+            : [
+                'OPEN A SESSION FIRST: begin_work({ task_id }) on the work item above. It attributes',
+                'what you produce to this run, and most tools refuse without it. end_work when you',
+                'finish.',
+            ]),
+        '',
+        /* ═══ 18c SLICE 3 — WHICH SURFACE THIS RUN ACTUALLY HAS. ═══
+    
+           This block used to name create_stage / create_step / update_step
+           unconditionally. Slice 3 closed those tools to runs with no work item,
+           which turned the instruction into the I8 defect one level up: a worker
+           steered by its own prompt into a route that now refuses it. The gate
+           measured the cost. Codex read the refusal, could not tell a closed route
+           from a bad id, went looking for a work item to borrow, and tried to hang
+           a panel request's plan on an unrelated real one.
+    
+           `canUseSession` IS "this run has a work item" (the orchestrator passes
+           `context.items.length > 0`), which is exactly the condition the three
+           tools now require, so the two cannot drift apart.
+    
+           report_activity is named in BOTH branches, because every run writes it
+           and the user watches it live either way. What differs is only whether
+           there is a plan to commit alongside it. */
+        'TO SHOW YOUR WORK AS IT HAPPENS: report_activity({ title }) whenever what you are',
+        'doing changes. The user watches live.',
+        /* THE PLAN IS A SEPARATE ACT FROM SAYING WHAT YOU ARE DOING, and only one of
+           them is available to every run. See the banner above. */
+        ...(canUseSession
+            ? [
+                'TO COMMIT THE PLAN: create_stage and create_step, then update_step as it changes,',
+                'in_progress when you start, done when finished. That is how any agent, on any',
+                'machine, picks the work up after you are gone.',
+                /* ═══ 18d SLICE 4 — WHERE A CONTINUATION LEARNS THE TOOL EXISTS. ═══
+      
+                   start_workflow's `remember` carries the same instruction, and that
+                   is NOT enough on its own: the run that picks up stage 2 never calls
+                   start_workflow (the workflow is already started, and a re-run is
+                   refused), so it would never hear of hand_off_stage and stage 3
+                   would never be reached. A two-stage fixture hides this entirely,
+                   which is why the walk uses three.
+      
+                   CHEAP BECAUSE IT IS CONDITIONAL. Only a run with a work item can
+                   have a process at all, so this costs nothing to the tools-only
+                   path, and the tool's own refusals cover a run whose item has no
+                   workflow stages. */
+                'IF THE ITEM CARRIES A WORKFLOW: work ONE stage. When its last step is done, call',
+                'hand_off_stage and end your run — a fresh agent takes the next stage from the',
+                'record. Never work two stages, and never hand over notes instead of records.',
+            ]
+            : [
+                'Steps are a WORK ITEM\'s plan and this has none, so create_stage refuses. Ask',
+                'for an item if this needs one, never borrow.',
+            ]),
+        /* ═══ 18c SLICE 7, GAP 8 — THE WORKER IS TOLD SCREENSHOTS EXIST. ═══
+           Spec: ux.md § "Slice 7", and story 4's scenario is the test: the user
+           types "show me what the recruiter search screen looks like at
+           http://localhost:8000/" and never says the word screenshot, and an image
+           has to come back rather than a description.
+    
+           IT HAD NEVER BEEN NAMED HERE. This block named present_mocks,
+           present_wireframes and draw_live_view; `attach_screenshot` appeared in
+           nothing a worker reads except the server instruction listing the tools
+           that REFUSE without a work item. So the single mention of the capability
+           in everything an agent ever saw was a statement of its limitation, which
+           is exactly why the tool shipped complete and uninvoked. Same failure as
+           skills and credentials before I10 named them.
+    
+           UNCONDITIONAL, unlike the three around it, because Slice 7 is what makes
+           that true: the tool now attaches to whichever anchor the session has, so
+           there is no branch where naming it would be naming a tool that refuses —
+           the mistake this function's header is about.
+    
+           IT SAYS WHEN, NOT JUST WHAT. "Whenever seeing it answers better than
+           reading about it" is the trigger the scenario needs; a worker told only
+           that the tool exists still writes a paragraph, because describing the
+           screen is what it would have done anyway. */
+        /* ═══ 18c SLICE 7, CORRECTED AT THE WALK — IT SAID "take a PNG", WHICH THE
+               WORKER CANNOT DO. ═══
+    
+           Naming the tool (above) was necessary and was not sufficient. The walk ran
+           story 4 on both platforms and every run finished `done` with no screenshot
+           and no tool call: `--permission-mode acceptEdits` approves file edits and
+           nothing else, so a headless worker's every non-read-only shell command is
+           refused by a CLI with no human to approve it. "Take a PNG" was an
+           instruction to do the one thing the run could not do, and an agent that
+           tries and is refused falls back to describing the screen in prose — which
+           is exactly what the walk saw.
+    
+           SO THE SENTENCE NAMES THE URL, NOT THE PNG. The product captures it now
+           (`captureUrlScreenshot`), and the worker's whole job is to pass the
+           address. Saying "you do not need a browser or a shell" is not padding: an
+           agent that has already been refused a command reasons that pictures are
+           impossible in this run, and has to be told otherwise in words. */
+        '',
+        'TO SHOW THE USER A REAL SCREEN: attach_screenshot({ url }) — CTRL+SPC opens the page',
+        'and captures it, so you need no browser and no shell. Whenever seeing it',
+        'answers better than reading about it, with or without a work item.',
+        ...(canUseSession
+            ? [
+                'ALSO: present_mocks or present_wireframes for something the user reviews;',
+                'draw_live_view for what you are working through right now, which is a picture of',
+                'the present and not a record. Anything that must outlive the run is an artifact, a',
+                'step or a comment.',
+            ]
+            : canAsk
+                ? [
+                    /* PHASE 4 (I12), kept and SHORTENED by Slice 1b. It used to have to
+                       explain that the worker could not record anything without an item;
+                       it can now, so only the reason an item is still worth having
+                       remains. `present_mocks` and `draw_live_view` are the tools that
+                       genuinely need one.
+        
+                       18c Slice 7: the blank line stays, and is now this block's own
+                       separator rather than the picture block's. The screenshot lines
+                       above are two sentences on one subject and this is a different
+                       one, so running them together loses the paragraph break the whole
+                       guidance is scanned by. */
+                    '',
+                    'IF SOMETHING MUST ACTUALLY BE BUILT — code, a schema change, a real deliverable',
+                    '— ASK FOR A WORK ITEM, with these EXACT values:',
+                    /* 18b SLICE 5 — THE QUESTION MUST BE A QUESTION (user, 2026-08-08).
+                       This used to say `question: <a specific name for the work item>`,
+                       because the web read that field verbatim as the created item's
+                       title. So the field labelled "Question" held a noun phrase, and
+                       the verb had to live in the options ("Create the work item" /
+                       "Not now"). `name` now carries the title, freeing the question to
+                       be one. Kept to the same length as what it replaced: the guidance
+                       has a hard character budget (test/tool-surface.test.mjs), and the
+                       shape below teaches the rule by showing it. */
+                    "  ask_question({ todo_id, category: 'work-item', context: <what you would build",
+                    "  and why>, name: 'Rework search ranking', question: 'Create a work item called",
+                    '  “Rework search ranking”?\', answer_mode: \'single_select\', options: [\'Yes\', \'No\'] })',
+                    '`name` is the bare title and becomes the work item verbatim; the question ASKS.',
+                    'Then STOP. Answering it creates the item and runs you again. Not for answering,',
+                    'explaining or looking things up, and never twice for the same thing.',
+                ]
+                : []),
+    ];
+}
+/**
+ * WHY THERE IS NOWHERE TO WORK, in the user's words — the phase's unhappy path.
+ *
+ * Returned as the request's ANSWER rather than raised as a failure, deliberately.
+ * A released unit is retried forever, and no number of retries will make a repo
+ * appear on this machine: the fix is a human locating it in the companion. So
+ * this is a finished request that says what to do, not a dead one that keeps
+ * trying. Nothing is spawned and nothing is modified.
+ */
+export function checkoutMissAnswer(miss) {
+    switch (miss.kind) {
+        case 'no-codebase':
+            return [
+                `This request needs the code, but ${miss.projectName || 'its project'} has no codebase registered.`,
+                '',
+                'Add one in the project\'s settings (Codebases → Add codebase), then send this again.',
+            ].join('\n');
+        case 'not-located':
+            return [
+                `This request needs the code, but ${miss.gitRemoteUrl} has not been located on this computer.`,
+                '',
+                'Open the CTRL+SPC companion on this machine and use Locate… on that codebase to point',
+                'it at your checkout, then send this again. Nothing was changed.',
+            ].join('\n');
+        case 'path-missing':
+            return [
+                `This request needs the code. ${miss.gitRemoteUrl} was located on this computer before,`,
+                'but that folder is gone — it was moved, renamed or deleted.',
+                '',
+                'Open the CTRL+SPC companion and use Locate… to point it at the checkout again, then',
+                'send this again. Nothing was changed.',
+            ].join('\n');
+        /* 18b Slice 2. NAMES THE CANDIDATES, because "several codebases" leaves the
+           user to go and find out which — and this refusal exists precisely so they
+           do not have to. Choosing one from the card is Slice 4; until then the fix
+           is to set a target, which is a real thing the user can do today. */
+        case 'ambiguous-codebase':
+            return [
+                `This request needs the code, but ${miss.projectName} has ${miss.gitRemoteUrls.length} codebases and`,
+                'nothing says which one to work in:',
+                '',
+                ...miss.gitRemoteUrls.map(url => `  · ${url}`),
+                '',
+                'Set the target codebase in the project\'s settings, then send this again. Nothing',
+                'was changed.',
+            ].join('\n');
+    }
+}
+/**
+ * !Cleanup PHASE 6b (I43) — TELL A REPLACEMENT THAT IT IS ONE.
+ *
+ * THE USER'S RULING, 2026-08-06: *"If a subagent dies, the subagent that picks
+ * it up must check the current state before working."*
+ *
+ * THE DEFECT THIS CLOSES. When a worker died the unit was released and a FRESH
+ * agent spawned with the ORIGINAL instruction and no idea any of it had happened.
+ * Meanwhile everything the dead run wrote is still there — work items,
+ * artifacts, steps, comments — and anything it did outside CTRL+SPC (files
+ * edited, a build run, a commit made) is not visible to any tool at all. So the
+ * retry did not resume, it REDID, on top of a board already holding half the
+ * work. The user cleans up the duplicates.
+ *
+ * WHY THIS IS NOT COVERED BY THE EXISTING "LOOK FOR IT FIRST" LINE. That line is
+ * generic advice a fresh agent may reasonably skim past on a task it believes is
+ * new. This is a specific, load-bearing FACT — *a previous attempt at this exact
+ * request already ran and stopped partway* — and it changes what the agent
+ * should do first. Guidance and a fact are not interchangeable here.
+ *
+ * DELIBERATELY NOT A SUMMARY OF WHAT THE DEAD RUN DID. The honest position is
+ * that the product does not know: no creation tool records which request it was
+ * working (that is I19, its own phase), so any list this text produced would be
+ * inferred and would be WRONG exactly when it mattered — naming work the run did
+ * not do, or missing work it did. Telling the agent to LOOK is true; telling it
+ * what it will find is not. The step line is the one honest exception: it is
+ * recorded against this unit's worker, so it is quoted when present.
+ */
+export function describeInterruptedRun(lastStep) {
+    const lines = [
+        '',
+        'A PREVIOUS ATTEMPT AT THIS REQUEST ALREADY RAN AND DID NOT FINISH. Its agent',
+        'stopped partway — killed, crashed, or the machine went away — so anything it had',
+        'already done IS STILL THERE. You are continuing, not starting.',
+    ];
+    if (lastStep) {
+        lines.push('', `The last thing it was seen doing: ${lastStep}`, 'That is where it stopped, not necessarily where it got to.');
+    }
+    lines.push('', 'SO CHECK BEFORE YOU BUILD. Call list_tasks and get_task, and look at the actual', 'files, before creating anything. If the work item, artifact or change you were', 'about to make already exists, USE IT and carry on from there — do not make a', 'second one. What you cannot see through the tools (a file that was edited, a', 'command that was run) you must check directly.', '', 'If it turns out the work was already finished, say so and stop. A duplicate is', 'worse than a no-op, because the user has to find it and clean it up.');
+    return lines;
+}