@ctrl-spc/cs 0.7.4 → 0.7.5

package/dist/daemon-lock.js

@@ -0,0 +1,48 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { configDir } from './config.js';
+import { processIsAlive } from './win-shell.js';
+/**
+ * One `cs start` per config dir.
+ *
+ * Two daemons on one machine share one `cliv2_agents` row and take turns
+ * overwriting it every heartbeat. The case that produced it: `cs start` was
+ * running, `npm i -g` replaced dist under it, and a second `cs start` came up
+ * on the new code. The row then flipped between 0.7.0 and 0.7.4 every few
+ * seconds and the Machines popover flickered with it.
+ *
+ * Keyed on the config dir, not the machine id, so the documented two-instance
+ * setup (`CTRL_SPC_V2_CONFIG_DIR` plus `CTRL_SPC_V2_MACHINE_ID`) still works.
+ *
+ * ponytail: a pid file, not an OS lock. A pid recycled onto an unrelated
+ * process after a crash reads as "already running" until that process exits;
+ * `rm ~/.config/ctrl-spc-v2/daemon.pid` is the way out. Upgrade to an
+ * exclusive-open lock if that is ever hit in practice.
+ */
+function lockPath() {
+    return join(configDir(), 'daemon.pid');
+}
+/** Claims the lock for this process, or returns the pid of the daemon that holds it. */
+export function claimDaemonLock() {
+    const path = lockPath();
+    if (existsSync(path)) {
+        const pid = Number(readFileSync(path, 'utf8').trim());
+        if (Number.isInteger(pid) && pid > 0 && pid !== process.pid && processIsAlive(pid)) {
+            return { held: true, pid };
+        }
+    }
+    mkdirSync(configDir(), { recursive: true });
+    writeFileSync(path, String(process.pid));
+    return { held: false };
+}
+/** Removes the lock if this process wrote it. Never throws: it runs during shutdown. */
+export function releaseDaemonLock() {
+    try {
+        const path = lockPath();
+        if (Number(readFileSync(path, 'utf8').trim()) === process.pid)
+            rmSync(path);
+    }
+    catch {
+        // no lock, or not ours
+    }
+}

package/dist/daemon.js

@@ -1,4 +1,5 @@
 import { ensureAutostart } from './autostart.js';
+import { claimDaemonLock, releaseDaemonLock } from './daemon-lock.js';
 import { liveClient, startPresence, stopPresence } from './presence.js';
 /* ═══ THE ONE IMPORT ANYTHING OUTSIDE `panel3/` MAKES INTO IT. ═══ Named in
    `.implementations/19-agent-panel-v3/conventions.md` and enforced by
@@ -28,6 +29,15 @@ import { startPanel } from './panel3/run.js';
  * starts doing the right thing with nothing else typed.
  */
 export async function runDaemon() {
+    /* One daemon per config dir. See daemon-lock.ts for the flicker this stops.
+       Exits rather than replacing the holder: under launchd's KeepAlive a
+       replacement would be restarted and would then replace the replacer. */
+    const lock = claimDaemonLock();
+    if (lock.held) {
+        console.error(`cs start is already running on this computer (pid ${lock.pid}). Stop it first to start another.`);
+        process.exitCode = 1;
+        return;
+    }
     ensureAutostart(); // default-on: install the login item unless the user opted out
     const { machineName, agents } = await startPresence();
     /* ═══ THE PANEL READS PRESENCE'S CLIENT, IT IS NOT HANDED A COPY OF IT. ═══
@@ -112,6 +122,7 @@ export async function runDaemon() {
            here (see `run()`). Both are best-effort and neither throws, which is why
            they can settle together. */
         await Promise.all([panel.stop(), stopPresence()]);
+        releaseDaemonLock();
         process.exit(code);
     }
     process.on('SIGINT', () => void shutdown());

package/dist/mcp.js

@@ -2019,11 +2019,8 @@ async function resolvePlacementTarget(client, table, noun, id, projectId) {
  * `epic_id` / `sprint_id` since 20260727080000 — with the fresh row's
  * revision, so the CAS contract is honored rather than bypassed.
  *
- * Sequencing fix: the create RPC's own position (min-1, top of backlog) is
- * right for a single human quick-add but inverts an agent-authored sequence,
- * so the placement pass runs for EVERY creation and moves the task to the
- * project's max(position)+1 — creation order equals board order. The
- * `position` key rides the same save_task_if_current p_changes whitelist.
+ * The create_task RPC appends at the bottom of the backlog, so creation order
+ * equals board order with no follow-up write.
  */
 export async function createTaskHandler(client, userId, currentSession, args, 
 /** 18c Slice 6: the request THIS CONNECTION is working. See
@@ -2044,25 +2041,6 @@ connectionTodoId = null) {
             if (!sprint.ok)
                 return sprint.error;
         }
-        // Feature 32 sequencing: the create_task RPC assigns position = min-1 (top
-        // of backlog — right for a single human quick-add), so N sequential agent
-        // creates would render NEWEST-FIRST on the board, inverting the skeleton's
-        // sequence. Read the project's current max position BEFORE the create so
-        // the placement pass below can APPEND the fresh task at max+1 — for every
-        // creation, placed or not, so creation order equals board order.
-        // (save_task_if_current's p_changes whitelist accepts `position`.) A
-        // concurrent-agent race on max+1 costs at worst an adjacent swap.
-        const maxPositionRow = await must(client
-            .from('tasks')
-            .select('position')
-            .eq('project_id', args.project_id)
-            .is('archived_at', null)
-            .order('position', { ascending: false })
-            .limit(1)
-            .maybeSingle());
-        const nextPosition = (typeof maxPositionRow?.position === 'number' && Number.isFinite(maxPositionRow.position)
-            ? maxPositionRow.position
-            : 0) + 1;
         const taskId = await must(client.rpc('create_task', {
             p_project: args.project_id,
             p_name: args.name,
@@ -2074,37 +2052,37 @@ connectionTodoId = null) {
         let task = await fetchTask(client, taskId);
         if (!task)
             throw new Error('Created task could not be re-fetched.');
-        // Place the fresh task on the board: append it at the project's max+1
-        // position (EVERY create — see the sequencing note above), plus its
-        // epic/sprint when given. The task row is COMMITTED by this point, so a
-        // placement failure is surfaced as a warning on the real result —
-        // reporting it as a failed create would make the agent retry and
-        // duplicate the task (the create_product_idea read-back lesson).
+        // Place the fresh task in its epic/sprint when either was given. The task
+        // row is COMMITTED by this point, so a placement failure is surfaced as a
+        // warning on the real result: reporting it as a failed create would make
+        // the agent retry and duplicate the task (the create_product_idea
+        // read-back lesson).
         let placementWarning;
-        try {
-            const revision = task.revision;
-            if (typeof revision !== 'number' || !Number.isInteger(revision) || revision < 1) {
-                throw new Error('the created task carried no usable revision');
+        if (args.epic_id !== undefined || args.sprint_id !== undefined) {
+            try {
+                const revision = task.revision;
+                if (typeof revision !== 'number' || !Number.isInteger(revision) || revision < 1) {
+                    throw new Error('the created task carried no usable revision');
+                }
+                await must(client.rpc('save_task_if_current', {
+                    p_task_id: taskId,
+                    p_expected_revision: revision,
+                    p_changes: {
+                        ...(args.epic_id !== undefined ? { epic_id: args.epic_id } : {}),
+                        ...(args.sprint_id !== undefined ? { sprint_id: args.sprint_id } : {}),
+                    },
+                    p_tag_ids: null,
+                    p_reorder: false,
+                    p_before_task_id: null,
+                }));
+                task = (await fetchTask(client, taskId)) ?? task;
+            }
+            catch (err) {
+                placementWarning =
+                    `The task was created (id ${taskId}) but placing it on the board (its epic/sprint) failed: ` +
+                        `${errorMessage(err)}. Do NOT create the task again; report the failed placement, ` +
+                        'a human can place it from the board.';
             }
-            await must(client.rpc('save_task_if_current', {
-                p_task_id: taskId,
-                p_expected_revision: revision,
-                p_changes: {
-                    position: nextPosition,
-                    ...(args.epic_id !== undefined ? { epic_id: args.epic_id } : {}),
-                    ...(args.sprint_id !== undefined ? { sprint_id: args.sprint_id } : {}),
-                },
-                p_tag_ids: null,
-                p_reorder: false,
-                p_before_task_id: null,
-            }));
-            task = (await fetchTask(client, taskId)) ?? task;
-        }
-        catch (err) {
-            placementWarning =
-                `The task was created (id ${taskId}) but placing it on the board (its position/epic/sprint) failed: ` +
-                    `${errorMessage(err)}. Do NOT create the task again — report the failed placement; ` +
-                    'a human can place it from the board.';
         }
         // D2a attribution: if this connection has an open session, record that the
         // session produced this NEW task — one cliv2_agent_outputs row referencing the

package/dist/panel3/prompt.js

@@ -664,6 +664,22 @@ export function workBrief(level, responsibility, boundary, workItemId, attachmen
                         'first stage only, and do not start the next stage until the one before it has come',
                         'back. When you send somebody for a stage, put that stage\'s own document into what you',
                         'give them, in full: they cannot read the workflow themselves.',
+                        /* ═══ 38-panel3-steps: THE STAGES LAND ON THE WORK ITEM, WHERE THE
+                           PERSON WATCHES. ═══ Without these sentences a panel run follows a
+                           workflow and the work item's Steps section stays empty: nothing
+                           starts the workflow on the item and nothing writes a step. The
+                           owner starts it once, hands each worker the work item, and reads
+                           the record before sending the next stage, because "the stage is
+                           finished" is what `up_next` moving on means and nothing else
+                           enforces the order. */
+                        'Before you send anybody for the first stage, call `start_workflow` with the workflow and',
+                        'the work item, once: it puts the stages on the work item, where the person watches. Pass',
+                        '`work_item_id` when you send somebody for a stage. When somebody comes back, call',
+                        '`list_steps` before you send the next stage. If `up_next` still names the stage you sent',
+                        'them for, that stage is not finished: send somebody back for what is left, or ask the',
+                        'person. Send the next stage only when `up_next` has moved on. A stage you work yourself',
+                        'gets the same record: `list_steps`, then `create_step` for each unit of work, then',
+                        '`update_step` as you go.',
                     ]
                     : []),
                 'What you have already sent somebody to do is written down, and you are handed that list',
@@ -685,6 +701,25 @@ export function workBrief(level, responsibility, boundary, workItemId, attachmen
                 '',
                 'Somebody else may be working in this same copy of the codebase at the same time as you, on',
                 'a different piece. Stay inside what you were given and leave the rest of it alone.',
+                /* ═══ 38-panel3-steps: A WORKER'S STAGE IS WRITTEN DOWN AS STEPS. ═══
+                   Printed only when a workflow is on the card, like the owner's clause
+                   above. The wording is the one v2's `start_workflow` reminder already
+                   uses, which a walked agent follows: decompose before working, tick as
+                   you go, only done moves the record on. It names no sequencing rule,
+                   because a worker sends nobody. */
+                ...(hasWorkflow
+                    ? [
+                        '',
+                        'THIS WORK FOLLOWS A WORKFLOW, AND ITS STEPS ARE WRITTEN DOWN WHERE THE PERSON WATCHES.',
+                        'Your stage is the first unfinished one on the work item: call `list_steps` with the work',
+                        'item id and read `up_next`. Before you do the stage\'s work, record its steps with',
+                        '`create_step`, one per unit of work, in order. Then `update_step` each to `in_progress`',
+                        'when you pick it up and `done` when it is finished; only done lets the next one start. If',
+                        'you cannot go on without an answer, `update_step` the step you are on to `blocked` with a',
+                        '`next_action` saying what you need, then `escalate`, then stop. Never create a second step',
+                        'to report on the first.',
+                    ]
+                    : []),
             ]),
         '',
         'WHAT YOU OWN',

package/dist/panel3/tools.js

@@ -127,6 +127,12 @@ import { workBrief } from './prompt.js';
 import { harness } from './spawn.js';
 import { listCodebases } from '../codebases.js';
 import { buildWorkflow, duplicateWorkflow, editWorkflow, readWorkflow, rewordStage } from '../workflows.js';
+/* ═══ 38-panel3-steps: THE FIFTH NEUTRAL MODULE, AND A DECISION LIKE THE OTHERS.
+   ═══ Stages and steps are the work item's own record, shared by both
+   generations and read by the web's Steps section. `steps.ts` owns the rows so
+   nothing here names a `cliv2_` table; conventions.md's enumeration and
+   `panel3-isolation.contract.test.mjs` were amended with it. */
+import { STEP_STATUSES, createStep, listSteps, stageById, startWorkflowOnItem, stepById, updateStep, } from '../steps.js';
 /* ═══ A THIRD GENERATION-NEUTRAL MODULE, AND IT IS A DECISION. ═══
    conventions.md enumerates what `panel3/` may reach outside itself and says
    "and nothing else", so this line amends that enumeration rather than slipping
@@ -706,6 +712,32 @@ function zeroBasedExits(exits, stageCount) {
 // read against the table it came from without hunting. `levels` on each entry is
 // the whole of the per-level rule; there is no second place where a level is
 // granted or taken away.
+/** 38-panel3-steps: the work item must be one this card carries. The person's
+ *  attachments are the authority on what a run may write to, exactly as
+ *  `attach_image_artifact` reads them before keeping a picture. */
+async function carriedWorkItem(caller, workItemId, consequence, attached) {
+    attached ??= await loadAttachments(caller.client, caller.cardId);
+    if (!attached.some((item) => item.kind === 'work_item' && item.ref_id === workItemId)) {
+        throw new Error(`NOTHING WAS WRITTEN: this card does not carry work item ${workItemId}, so ${consequence}. `
+            + 'get_my_brief_and_report and what was attached name the work item you are on.');
+    }
+}
+/** The stage a step write may land in: a real row, anchored to a work item this
+ *  card carries. A stage anchored to a panel request has no Steps section to
+ *  show it, so it is refused by name and the agent is pointed at the card. */
+async function stageForWriting(caller, stageId, consequence) {
+    const stage = await stageById(caller.client, stageId);
+    if (!stage) {
+        throw new Error(`NOTHING WAS WRITTEN: there is no stage ${stageId}, or it is not yours. list_steps names them.`);
+    }
+    if (!stage.workItemId) {
+        throw new Error(`NOTHING WAS WRITTEN: stage ${stageId} belongs to a panel request rather than a work item, and `
+            + 'steps are a WORK ITEM\'s record. What you are doing already goes on the card: call '
+            + 'report_activity. If this work deserves a work item of its own, ask for one.');
+    }
+    await carriedWorkItem(caller, stage.workItemId, consequence);
+    return stage;
+}
 const TOOLS = [
     // ── Read the record ──────────────────────────────────────────────────────
     {
@@ -1253,6 +1285,139 @@ const TOOLS = [
                 + 'as the original, so reword_stage on either rewords both.';
         },
     },
+    // ── Steps: the work item's own record of a workflow run ──────────────────
+    /* ═══ 38-panel3-steps: A PANEL RUN THAT FOLLOWS A WORKFLOW WRITES THE WORK
+       ITEM'S STEPS. ═══ The Steps section, its tables, its live refresh and the
+       board card's progress chip all existed; what did not exist was a writer on
+       this side. v2's own step tools refuse anything but a v2 session and gate on
+       v2's scope contract, which a panel run never has, so these four are served
+       here over the neutral module.
+  
+       THE GATE IS THE CARD'S ATTACHMENTS, exactly as `attach_image_artifact`
+       gates a picture: the person pointed this conversation at a work item, and
+       that row is the authority on what a run may write to. A stage anchored to
+       a panel request rather than a work item is refused outright, because the
+       Steps section that would show it lives on a work item (decision 1 on the
+       work item's spec). Provenance is copied from the stage by the module, never
+       chosen here.
+  
+       WHO HOLDS WHAT. `start_workflow` is the owner's, like `get_workflow`: only
+       level 2 sees the attachment list and reads the process. The three that
+       write and read steps are levels 2 and 3, because a worker owns one stage
+       and the owner may work a record-only stage itself. Level 1 launches and
+       exits and holds none of them. */
+    {
+        name: 'start_workflow',
+        levels: [2],
+        description: 'Put the attached workflow\'s stages on the attached work item, once, before you send anybody '
+            + 'for the first stage. The person watches progress on the work item, so a workflow that is '
+            + 'not started there is a workflow they cannot see. Call it again and nothing is written twice.',
+        input: {
+            workflow_id: z.string().uuid().describe('The id printed beside the workflow in what was attached.'),
+            work_item_id: z.string().uuid().describe('The id printed beside the work item in what was attached.'),
+        },
+        handler: async (caller, args) => {
+            const { workflow_id, work_item_id } = args;
+            const attached = await loadAttachments(caller.client, caller.cardId);
+            if (!attached.some((item) => item.kind === 'workflow' && item.ref_id === workflow_id)) {
+                throw new Error(`NOTHING WAS WRITTEN: this card does not carry workflow ${workflow_id}. Use the id printed `
+                    + 'beside the workflow in what was attached.');
+            }
+            await carriedWorkItem(caller, work_item_id, 'a workflow cannot be started on it', attached);
+            const workflow = await readWorkflow(caller.client, workflow_id);
+            const result = await startWorkflowOnItem(caller.client, work_item_id, workflow_id);
+            return result.started
+                ? `The ${result.stages} stages of ${workflow.name} are on work item ${work_item_id}. Work them in `
+                    + 'order: send somebody for stage 1, and nobody for stage 2 until list_steps shows stage 1\'s '
+                    + 'steps are all done.'
+                : `${workflow.name} is already on work item ${work_item_id} (${result.stages} stages); nothing was `
+                    + 'written twice. Call list_steps to see where it is.';
+        },
+    },
+    {
+        name: 'list_steps',
+        levels: [2, 3],
+        description: 'The stages on a work item, the steps recorded inside each, and UP NEXT: the one thing that '
+            + 'should happen next, computed by the product and read by the person too. "decompose" means '
+            + 'the named stage has no steps yet and writing them is the next action; "step" names the one '
+            + 'to work; "none" means nothing is waiting. Read it before you record or send anything.',
+        input: {
+            work_item_id: z.string().uuid().describe('The work item, from what was attached or your brief.'),
+        },
+        handler: async (caller, args) => {
+            const { work_item_id } = args;
+            await carriedWorkItem(caller, work_item_id, 'its steps cannot be read from here');
+            const spine = await listSteps(caller.client, work_item_id);
+            if (spine.stages.length === 0) {
+                return `Work item ${work_item_id} has no stages. Nothing has been started on it.`;
+            }
+            return [
+                `STAGES  ${spine.stages.length} on work item ${work_item_id}`,
+                ...spine.stages.flatMap((stage, i) => {
+                    const done = stage.steps.filter((step) => step.status === 'done').length;
+                    const summary = stage.steps.length === 0 ? 'no steps yet' : `${done} of ${stage.steps.length} done`;
+                    return [
+                        '',
+                        `${i + 1}. ${stage.title}   id ${stage.id}   ${stage.sourceKind} · ${stage.sourceLabel}   ${summary}`,
+                        ...stage.steps.map((step, j) => `   ${i + 1}.${j + 1} ${step.title}   [${step.status}]   id ${step.id}\n`
+                            + `       next: ${step.nextAction}`),
+                    ];
+                }),
+                '',
+                'UP NEXT',
+                JSON.stringify(spine.upNext, null, 2),
+            ].join('\n');
+        },
+    },
+    {
+        name: 'create_step',
+        levels: [2, 3],
+        description: 'Record one step inside a stage of the work item, before you do it. A step is a resumable unit '
+            + 'of work: its charter says why it exists and what done looks like, its next action is the one '
+            + 'literal thing to do first, and its position orders it inside the stage. Record every step '
+            + 'of a stage before working the first; the person reads these as the run moves. '
+            + FIREWALL_WRITING_RULE,
+        input: {
+            stage_id: z.string().uuid().describe('The stage this step belongs to, from list_steps.'),
+            title: z.string().min(1).describe('A few words, as the person will read them in the list.'),
+            charter: z.string().min(1).describe('Why the step exists and how you would know it is done.'),
+            next_action: z.string().min(1).describe('The one literal thing to do first. Repo-relative paths only.'),
+            position: z.number().int().describe('Order inside the stage, from 1.'),
+        },
+        handler: async (caller, args) => {
+            const { stage_id, title, charter, next_action, position } = args;
+            const stage = await stageForWriting(caller, stage_id, 'a step cannot be recorded under it');
+            const { id } = await createStep(caller.client, stage, { title, charter, nextAction: next_action, position });
+            return `Recorded step ${position} "${title}" under ${stage.title}, id ${id}, status pending. Call `
+                + 'update_step with status in_progress when you pick it up.';
+        },
+    },
+    {
+        name: 'update_step',
+        levels: [2, 3],
+        description: 'Change a step you or somebody else recorded: in_progress when you pick it up, done when it is '
+            + 'finished, blocked with a next_action naming what you need when you cannot go on. Rewrite '
+            + 'next_action as it changes. Only done lets the next step start. A step\'s stage, position and '
+            + 'source cannot change; nothing is written when nothing would change. '
+            + FIREWALL_WRITING_RULE,
+        input: {
+            step_id: z.string().uuid().describe('The step, from list_steps or create_step.'),
+            title: z.string().optional(),
+            charter: z.string().optional(),
+            next_action: z.string().optional(),
+            status: z.enum(STEP_STATUSES).optional(),
+        },
+        handler: async (caller, args) => {
+            const { step_id, title, charter, next_action, status } = args;
+            const step = await stepById(caller.client, step_id);
+            if (!step) {
+                throw new Error(`NOTHING WAS WRITTEN: there is no step ${step_id}, or it is not yours. list_steps names them.`);
+            }
+            await stageForWriting(caller, step.stageId, 'its step cannot be changed');
+            const result = await updateStep(caller.client, step, { title, charter, nextAction: next_action, status });
+            return `Updated ${result.updated.join(', ')} on "${title ?? step.title}"; status is now ${status ?? step.status}.`;
+        },
+    },
     {
         name: 'get_credential',
         /* ═══ LEVELS 2 AND 3, AND THAT IS A CORRECTION TO ux.md's OWN TABLE. ═══

package/dist/steps.js

@@ -0,0 +1,168 @@
+import { absolutePathToken } from './local-paths.js';
+export const STEP_STATUSES = ['pending', 'in_progress', 'blocked', 'interrupted', 'done'];
+const STAGE_COLUMNS = 'id, work_item_id, title, position, source_kind, source_label, source_ref, source_workflow_ref';
+const STEP_COLUMNS = 'id, stage_id, title, charter, next_action, status, position, source_kind, source_label, source_ref';
+async function read(query, subject) {
+    const { data, error } = await query;
+    if (error)
+        throw new Error(`could not read ${subject}: ${error.message}`);
+    return data ?? [];
+}
+const stageOf = (row) => ({
+    id: row.id,
+    workItemId: row.work_item_id,
+    title: row.title,
+    position: row.position,
+    sourceKind: row.source_kind,
+    sourceLabel: row.source_label,
+    sourceRef: row.source_ref,
+    sourceWorkflowRef: row.source_workflow_ref,
+});
+const stepOf = (row) => ({
+    id: row.id,
+    stageId: row.stage_id,
+    title: row.title,
+    charter: row.charter,
+    nextAction: row.next_action,
+    status: row.status,
+    position: row.position,
+    sourceKind: row.source_kind,
+    sourceLabel: row.source_label,
+    sourceRef: row.source_ref,
+});
+/** Refuse prose that carries an absolute local path, before it is written. */
+function sweep(action, prose) {
+    for (const [field, value] of prose) {
+        const token = value === undefined ? null : absolutePathToken(value);
+        if (token) {
+            throw new Error(`could not ${action}: ${field} contains an absolute local path ("${token}"). It is rendered `
+                + 'by hosted browser JS and must never leave this machine; name files repo-relative. '
+                + 'Nothing was written.');
+        }
+    }
+}
+/** The stages on one work item, in the order they are worked. */
+export async function stagesOnItem(client, workItemId) {
+    const rows = await read(client.from('cliv2_stages').select(STAGE_COLUMNS).eq('work_item_id', workItemId)
+        .order('position', { ascending: true }).order('created_at', { ascending: true }), `the stages of work item ${workItemId}`);
+    return rows.map(stageOf);
+}
+/** One stage by id, or null when there is no such row or it is not the caller's. */
+export async function stageById(client, stageId) {
+    const rows = await read(client.from('cliv2_stages').select(STAGE_COLUMNS).eq('id', stageId), `stage ${stageId}`);
+    return rows.length === 0 ? null : stageOf(rows[0]);
+}
+/** One step by id, or null when there is no such row or it is not the caller's. */
+export async function stepById(client, stepId) {
+    const rows = await read(client.from('cliv2_steps').select(STEP_COLUMNS).eq('id', stepId), `step ${stepId}`);
+    return rows.length === 0 ? null : stepOf(rows[0]);
+}
+/**
+ * Put a workflow's stages on a work item, once.
+ *
+ * `cliv2_start_workflow` is the one guard: it refuses a workflow already on
+ * the item, atomically, with "already started". That refusal is turned into a
+ * calm `{ started: false }` here, because an owner restarted at a stage
+ * boundary calls this again and must not read its own earlier success as a
+ * failure. Any other refusal comes back verbatim.
+ */
+export async function startWorkflowOnItem(client, workItemId, workflowId) {
+    const { data, error } = await client.rpc('cliv2_start_workflow', {
+        p_work_item_id: workItemId,
+        p_workflow_id: workflowId,
+    });
+    if (error) {
+        if (/already started/i.test(error.message)) {
+            const existing = (await stagesOnItem(client, workItemId))
+                .filter((stage) => stage.sourceWorkflowRef === workflowId);
+            return { started: false, stages: existing.length };
+        }
+        throw new Error(`could not start workflow ${workflowId} on work item ${workItemId}: ${error.message}. `
+            + 'Nothing was written.');
+    }
+    return { started: true, stages: Number(data) };
+}
+/** The whole spine of one work item plus the one shared "up next". */
+export async function listSteps(client, workItemId) {
+    const stages = await stagesOnItem(client, workItemId);
+    const steps = stages.length === 0 ? [] : await read(client.from('cliv2_steps').select(STEP_COLUMNS).in('stage_id', stages.map((stage) => stage.id))
+        .order('position', { ascending: true }).order('created_at', { ascending: true }), `the steps of work item ${workItemId}`);
+    const { data: upNext, error } = await client.rpc('cliv2_steps_up_next', { p_work_item_id: workItemId });
+    if (error)
+        throw new Error(`could not read what is up next on work item ${workItemId}: ${error.message}`);
+    return {
+        stages: stages.map((stage) => ({
+            ...stage,
+            steps: steps.filter((row) => row.stage_id === stage.id).map(stepOf),
+        })),
+        upNext,
+    };
+}
+/**
+ * Record one step inside a stage. Provenance is COPIED FROM THE STAGE, never
+ * chosen by the caller: a step under a workflow stage says which workflow, and
+ * a step under a plan stage says which plan, and an agent cannot mislabel one.
+ */
+export async function createStep(client, stage, input) {
+    const action = `record the step "${input.title}"`;
+    for (const [field, value] of [['title', input.title], ['charter', input.charter], ['next_action', input.nextAction]]) {
+        if (value.trim() === '')
+            throw new Error(`could not ${action}: ${field} is blank. Nothing was written.`);
+    }
+    if (!Number.isInteger(input.position)) {
+        throw new Error(`could not ${action}: position must be a whole number. Nothing was written.`);
+    }
+    sweep(action, [['title', input.title], ['charter', input.charter], ['next_action', input.nextAction]]);
+    const rows = await read(client.from('cliv2_steps').insert({
+        stage_id: stage.id,
+        title: input.title,
+        charter: input.charter,
+        next_action: input.nextAction,
+        position: input.position,
+        source_kind: stage.sourceKind,
+        source_label: stage.sourceLabel,
+        source_ref: stage.sourceRef,
+    }).select('id'), `the step just written under stage ${stage.id}`);
+    if (rows.length === 0)
+        throw new Error(`could not ${action}: the write returned no row.`);
+    return { id: rows[0].id };
+}
+/**
+ * Change a step's living fields. The database grants update on exactly these
+ * four columns, so a stage, position or provenance change is refused there
+ * whatever a caller sends; this refuses the two things the database cannot see:
+ * a call that changes nothing, and a blank string offered as a way to clear.
+ */
+export async function updateStep(client, step, changes) {
+    const action = `update the step "${step.title}"`;
+    const patch = {};
+    const updated = [];
+    const consider = (field, next, current) => {
+        if (next === undefined)
+            return;
+        if (next.trim() === '') {
+            throw new Error(`could not ${action}: ${field} is blank. A field cannot be cleared; nothing was written.`);
+        }
+        if (next === current)
+            return;
+        patch[field] = next;
+        updated.push(field);
+    };
+    if (changes.status !== undefined && !STEP_STATUSES.includes(changes.status)) {
+        throw new Error(`could not ${action}: "${changes.status}" is not a status. Use one of ${STEP_STATUSES.join(', ')}. `
+            + 'Nothing was written.');
+    }
+    consider('title', changes.title, step.title);
+    consider('charter', changes.charter, step.charter);
+    consider('next_action', changes.nextAction, step.nextAction);
+    consider('status', changes.status, step.status);
+    if (updated.length === 0) {
+        throw new Error(`could not ${action}: nothing would change. Nothing was written.`);
+    }
+    sweep(action, [['title', changes.title], ['charter', changes.charter], ['next_action', changes.nextAction]]);
+    const rows = await read(client.from('cliv2_steps').update(patch).eq('id', step.id).select('id'), `the step just updated (${step.id})`);
+    if (rows.length === 0) {
+        throw new Error(`could not ${action}: the update matched no row, so nothing was written.`);
+    }
+    return { id: step.id, updated: updated.sort() };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctrl-spc/cs",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "description": "CTRL+SPC — minimal, reliable per-machine agent presence. Sign-in, auto-start, agent detection, heartbeat presence, and ping acknowledgement.",
   "engines": {
     "node": ">=22"