@ctrl-spc/cs 0.7.0 → 0.7.2

package/dist/presence.js

@@ -2,6 +2,7 @@ import { platform } from 'node:os';
 import { getClient } from './supabase.js';
 import { getMachineIdentity, mcpToken, supersededMachineIds, clearSupersededMachineIds } from './config.js';
 import { detectAgents } from './agents.js';
+import { installSkills } from './skills.js';
 import { startToolsServer, stopToolsServer, toolsServerStatus, registerWithClaude, registerWithCodex, unregisterFromClaude, unregisterFromCodex, agentRegStatus, heartbeatOpenSessions, setToolsClient, } from './mcp.js';
 import { HEARTBEAT_INTERVAL_MS, COMMAND_POLL_INTERVAL_MS, ORCHESTRATOR_POLL_INTERVAL_MS } from './env.js';
 import { buildPresenceHeartbeatPayload } from './presence-heartbeat.js';
@@ -317,6 +318,13 @@ export async function startPresence() {
         // presence heartbeat above, so it's caught and warned like everything here.
         try {
             await startToolsServer({ client, userId, machineId: identity.id });
+            /* The instructions belong to the release, so they are rewritten beside
+               registration on every start: the pair is "make this machine's agents
+               ready", and a machine registered against current tools while reading a
+               stale document is the exact failure this rewrite exists to kill. */
+            const unwritten = installSkills(agents);
+            if (unwritten.length)
+                console.warn(`Could not write the ctrl-spc skill: ${unwritten.join(', ')}`);
             if (agents.includes('claude'))
                 registerWithClaude(toolsServerStatus().port);
             if (agents.includes('codex'))

package/dist/skills.js

@@ -0,0 +1,165 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/**
+ * THE INSTRUCTIONS THE AGENT FOLLOWS ARE THE RELEASE'S, NOT THE MACHINE'S.
+ *
+ * These files used to be written only by the deprecated v1 CLI, so on a machine
+ * that stopped running v1 they froze: every installed copy still ends in
+ * `Tools live at http://localhost:4590/mcp`, a port this product has NEVER used
+ * (the real one is 4579, and an agent reaches the tools BY NAME, with no address
+ * at all). An agent whose tools were missing therefore probed a dead port,
+ * concluded the server was down, and told the user to repair a machine that was
+ * working. Writing them from `cs` on every start is what makes an install unable
+ * to disagree with itself.
+ */
+// Verbatim from the web/skill contract the copied `/ctrl-spc work <id>`
+// invocation depends on.
+const SKILL_DESCRIPTION = 'Work a CTRL+SPC work item or artifact by ID — delegates read-only exploration and writes analysis/plans/specs/diagrams/mocks/wireframes back via the ctrl-spc MCP tools. Use when the user pastes /ctrl-spc work <id> or /ctrl-spc artifact <id>.';
+/** Home the skill files are written under. `CTRL_SPC_HOME` is the existing
+ *  documented name for exactly this (docs/cli-surface-catalog.md), reused
+ *  rather than renamed so one machine has one sandbox-home concept. */
+function skillHome() {
+    return process.env.CTRL_SPC_HOME || homedir();
+}
+function claudeSkillPath() {
+    return join(skillHome(), '.claude', 'skills', 'ctrl-spc', 'SKILL.md');
+}
+/**
+ * Codex's three. `.agents` is NOT optional and not a legacy leftover: it is a
+ * second skill root that no isolation reaches (not a per-run `CODEX_HOME`, not
+ * `--ignore-user-config`, not `skill_search = false`, all three measured in
+ * codex-home.ts), and a resolved bug recorded that in 9 of 9 isolated runs
+ * Codex's FIRST action was to read that exact file. The leak cannot be closed
+ * here; what can be fixed is that the document it leaks is current.
+ */
+function codexTargets() {
+    return [
+        { path: join(skillHome(), '.agents', 'skills', 'ctrl-spc', 'SKILL.md'), text: SKILL_TEXT },
+        { path: join(skillHome(), '.codex', 'skills', 'ctrl-spc', 'SKILL.md'), text: SKILL_TEXT },
+        // The deprecated custom-prompt file, kept as a fallback for users who still
+        // invoke it explicitly as `/prompts:ctrl-spc ...`. No frontmatter.
+        { path: join(skillHome(), '.codex', 'prompts', 'ctrl-spc.md'), text: PROMPT_TEXT },
+    ];
+}
+/**
+ * Write the ctrl-spc skill for each detected agent. ALWAYS OVERWRITES (Lane,
+ * 2026-08-26): no content comparison, no prompt, no backup, so a hand-edited or
+ * stale file cannot outlive the release that contradicts it.
+ *
+ * Returns the paths it could not write rather than only warning, and never
+ * throws: a SILENT write failure leaves the agent reading the stale file while
+ * the daemon reports itself healthy, which is precisely the failure this exists
+ * to kill. Registration must not break because a skill file could not be
+ * written, so the caller warns and carries on.
+ */
+export function installSkills(agents) {
+    const targets = [
+        ...(agents.includes('claude') ? [{ path: claudeSkillPath(), text: SKILL_TEXT }] : []),
+        ...(agents.includes('codex') ? codexTargets() : []),
+    ];
+    const failed = [];
+    for (const { path, text } of targets) {
+        try {
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(path, text, 'utf8');
+        }
+        catch {
+            failed.push(path);
+        }
+    }
+    return failed;
+}
+/**
+ * The working protocol, then the section that matters here: what an agent does
+ * when the tools are NOT in its list. It names no address, because there is
+ * none to name — `cs status` is the only diagnosis.
+ */
+const PROTOCOL_BODY = `Resolve a CTRL+SPC work item or artifact pasted as \`/ctrl-spc work <id>\` or \`/ctrl-spc artifact <id>\`, then follow the ctrl-spc working protocol:
+
+WORKFLOW AUTHORITY — when \`get_task.workflow.enabled\` is true, follow only its current stage, stored instructions, capabilities, requirements, and gate. Never infer or skip a stage. Persist each required artifact, then call \`hand_off_stage\` with the work item id and this request id, and stop: the next stage is worked by a fresh agent reading the record. It refuses a stage with unfinished steps and the last stage of the process, where you answer and stop instead. Review gates advance only after explicit user approval in the web app or conversation; requested changes stay in the same stage. Only final approval sets Done.
+
+HARD STOP — unclear novel feature (No workflow only): when \`workflow.enabled\` is false, after \`record_context_exploration\` succeeds, if the task does not explicitly request a build or name a deliverable, the next tool call MUST be \`ask_question\` with category \`intent\`, the exact question “What should I produce for this feature?”, \`answer_mode = multi_select\`, and options \`build\`, \`plan\`, \`spec\`, \`diagram\`, \`mock\`, and \`wireframe\`. Then call \`end_work\` with reason \`pending_user_answer\` and outcome \`blocked\`. In that run, never call \`get_task\` again, \`update_task\`, \`create_artifact\`, \`reserve_work_paths\`, or any other tool between the context artifact and \`ask_question\`. The context artifact is the only allowed artifact. Do not copy findings into the task description before the user answers. A read-only execution sandbox is not a missing checkout and must not change this intent question. The user may select one or more: build, plan, spec, diagram, mock, wireframe.
+
+Before the context artifact exists, never state or imply a requested deliverable and never mention repository counts, contents, tests, findings, or likely impact. If progress commentary is required, use only: “The required CTRL+SPC context review is in progress; no decision or repository change has been made.” After the context artifact and before the intent question, either say nothing or use only: “The required context review is saved to the work item. I am applying the task's explicit intent gate now.”
+
+1. Resolve without side effects — call \`get_task\` before anything else. It is read-only: it does not change status, presence, claims, or reservations. The ID is the only context in the paste; everything current lives in ctrl-spc.
+2. Begin explicitly — call \`begin_work\` after reading the topology. If the user supplied an exact instruction alongside the copied command, pass it as \`prompt_instruction\`; never invent one. The first live run is coordinator and \`begin_work\` moves Backlog to In Progress; later runs join as collaborators. Only the coordinator changes status. Never mark an item \`done\` autonomously.
+3. Repair missing context — if \`begin_work\` reports an unavailable checkout, warn the user and offer to fetch or link it. Never fetch without approval. If the user explicitly continues without it, call \`acknowledge_unavailable_checkout\`, then call \`begin_work\` again after every missing scope is fetched or acknowledged.
+4. Delegate exploration — every pasted work item MUST use at least one read-only subagent. After \`begin_work\` joins, partition every available repository scope exactly once across bounded subagent invocations. Every child prompt must explicitly list its assigned \`repository_scope_ids\`; across the batch each available ID appears exactly once. When using Codex \`spawn_agent\`, MUST pass \`fork_turns: "none"\`; never pass \`all\` or a recent-turn count. Give each child a self-contained assignment containing only its exact scope IDs, checkout paths, inspection focus, read-only restrictions, and required report shape. Never include or inherit the parent \`/ctrl-spc work\` command. The child must not call any ctrl-spc tool—including \`get_task\` or \`begin_work\`—or pick up the work item; it only inspects assigned paths and returns its report. If zero scopes are available after explicit acknowledgements, one child inspects the task/artifact context and reports those unavailable scopes without pretending they were reviewed. Children inspect only: no file mutation, path reservation, ctrl-spc call, \`tee\`, shell redirection, temp/capture file, install, formatter, cache-generating command, or any command that can write. Inspection-first is sufficient; do not decide intent before reports are persisted. Each report uses \`{ agent, focus, repository_scope_ids, inspected_paths, findings, likely_impact, unresolved_questions }\`. If no subagent is available, do not explore directly: call \`record_context_exploration\` with \`blocked_reason = subagents_unavailable\`, tell the user, and stop.
+5. Persist context before deciding — the parent consolidates every child report and MUST call \`record_context_exploration\` to create or update the work item's stable-purpose context artifact before deciding what to do, asking a task question, planning, reserving, or editing. Every agent and workflow stage revises the same task-level context artifact instead of creating another card. Pass the structured reports plus a separate coverage array; include every active repository scope exactly once, and give unavailable scopes their acknowledgement. Before the tool succeeds, commentary may state process only: never disclose findings, conclusions, likely impact, or decisions. After persistence, terminal summaries may reference the persisted artifact/question but must add no unpersisted facts.
+6. Decide or ask deterministically — assigned workflow stage data decides the work. Without a workflow, classify intent only from the work item's explicit wording and accepted answers, never from findings. Findings do not authorize a deliverable. Infer and perform the action only when the item explicitly names it. Otherwise persist only the necessary question with \`ask_question\`. Choose \`free_text\` for an open response, \`single_select\` for exactly one choice, or \`multi_select\` for one or more choices; choice modes require 2–12 concise, unique options. For a bug, ask for reproduction steps, expected behavior, or actual behavior only when each is missing and not discoverable. For a novel feature with no explicit build action or deliverable, apply the HARD STOP above: the mandatory next mutating call after \`record_context_exploration\` is the specified multi-select \`ask_question\`. Generic goals such as “improve,” “coordinate,” “prepare,” or “support” are not deliverables. In this state do not call \`update_task\`, \`create_artifact\`, \`reserve_work_paths\`, or \`create_task\`; do not decide, edit, or complete. The context analysis is the only allowed artifact before the answer. Ask before overriding an unmet dependency, splitting work, fetching, or accepting a collision handoff. After \`ask_question\` succeeds, do no more work in that run: call \`end_work\` with reason \`pending_user_answer\` and outcome \`blocked\`, then wait for a later pasted run.
+7. Persist every accepted answer and finding — \`ask_question\` creates first-class decisions and returns decision IDs for the web app to display and answer. When the user answers in the agent conversation instead, use \`record_user_input\` with one structured response per Decision: \`decision_id\`, \`selected_options\`, and optional \`answer_note\`. The legacy decision IDs plus exact-answer shape is free-text only. Decisions create no answer artifact and are not copied into the task description. Do not use progress comments; do not leave findings only in the terminal.
+8. Reserve before writing — read-only stages never reserve writes or edit files. When the current stage allows writes, call \`reserve_work_paths\` for the exact checkout and paths; never edit through a collision. Never edit a conflicting path; narrow the reservation or use an isolated Git worktree.
+9. Persist every substantive non-question output — give every artifact a clear title and stable \`purpose_key\`. Call \`create_artifact\` for a new purpose and \`update_artifact\` with the latest revision when the same purpose already exists; a different purpose creates a different artifact. Every artifact must have exactly one coverage disposition for every active repository scope. For workflow tasks, persist every required artifact first and then call \`hand_off_stage\`; it refuses while any step of the stage is unfinished. Plan approval is displayed on the submitted plan and is not a decision artifact. Never write planning documents into a repository.
+10. Split only with approval — when work is too large, use \`ask_question\`; on approval create dependency-linked items with \`create_task\`, a shared feature tag, and matching board order.
+11. Keep the item self-sufficient — questions and accepted answers are persisted as first-class decisions through \`ask_question\` and \`record_user_input\`; substantive outputs live in artifacts. Do not use progress comments; \`add_comment\` is not for routine progress. A fresh agent must need no terminal, chat, or subagent history.
+12. End with proof — release finished reservations with \`release_work_paths\`, then call \`end_work\` with \`persistence_receipt = { final_task_revision, artifact_ids, outcome }\`. \`artifact_ids\` must exactly match every live artifact produced by this run and include the context-exploration artifact. Use outcome \`completed\` only for finished work, \`blocked\` for a persisted question or unavailable subagents, and \`aborted\` only when intentionally abandoning the run. A missing, stale, foreign, duplicate, or incomplete receipt is rejected; ending releases only this session's work.Full protocol: MCP prompt \`ctrl-spc-protocol\`.
+
+## If the ctrl-spc tools are not in your tool list
+
+First check your own tool list. **If the ctrl-spc tools are there, this section
+does not apply**: do the work, and do not run \`cs status\` at all. Read on only if
+they are actually missing.
+
+The tools are registered into your agent by the CTRL+SPC daemon and are called by
+name. There is no address to connect to.
+
+**Diagnose it yourself. Do not ask the user to.** Run \`cs status\` and follow the
+single next step it prints. Never probe a network address, never name a port,
+never report the CTRL+SPC server down, and never hand the user a command whose
+purpose is to find out what is wrong. The only things you ask the user for are
+their password, permission to run something, and restarting their agent.
+
+**Never suggest project configuration.** This is not per-project setup. Do not
+create or suggest \`.mcp.json\`, a \`.claude/\` directory, or any file in the
+project. If the tools are missing, the machine needs setup, not the codebase.
+
+**Do one step per turn, in order.** Act only on the step \`cs status\` just
+printed, never on one you expect to come next. The order is forced: sign in, then
+start, then restart, and an earlier step must succeed before a later one can
+work. Never ask for two things at once.
+
+Act on what it says:
+
+- **\`cs\` is not found at all.** CTRL+SPC is not installed on this machine. Tell
+  the user, and offer to run \`npm i -g @ctrl-spc/cs\`. Ask before running it.
+- **It says to sign in.** Tell the user to run \`cs login\` themselves, and that a
+  browser will open where they sign in with the same email and password they use
+  on ctrl-spc.com. Do not run \`cs login\` yourself: it waits up to five minutes
+  for that browser. Then stop your turn and hand control back, saying you will
+  continue when they tell you sign-in is done. When they say it is done, run
+  \`cs status\` again yourself, tell them which account it shows, and carry on with
+  the step it now prints.
+- **It says to run \`cs start\`.** Ask permission first, and tell the user it stays
+  running in the background to keep their computer online for CTRL+SPC.
+  \`cs start\` never exits on its own, so never run it as a command you wait on:
+  run exactly \`nohup cs start > /dev/null 2>&1 &\` (on Windows,
+  \`start /b cs start\`). Wait a few seconds, then run \`cs status\` again. If your
+  tools cannot leave a process running after a command returns, say so and ask
+  the user to run \`cs start\` in their own terminal window instead.
+- **It says the tools are not registered into an agent.** Ask permission to
+  restart the background daemon, then start it again the same way, and run
+  \`cs status\` again. Do not ask the user to press Ctrl-C.
+- **It says to restart your agent.** Ask the user to restart it, pass on the
+  reason \`cs status\` gave, and tell them the pasted work item will run once it
+  comes back.
+
+If a command you ran fails, say which command failed and what it said. \`cs status\`
+exiting non-zero is **not** one of those failures: it exits non-zero whenever
+setup is not yet finished, which only means there is another step. Judge it by
+what it prints, never by its exit code, and never treat a non-zero \`cs status\`
+after a repair as proof the repair failed. Never report setup as complete on the
+strength of a command you did not confirm with a fresh \`cs status\`.
+`;
+/** The three SKILL.md files. Byte-identical for Claude and Codex: the protocol
+ *  is the same document, and one constant means they cannot drift apart the way
+ *  v1's two copies did (Codex's still named a tool that no longer exists). */
+const SKILL_TEXT = `---
+name: ctrl-spc
+description: ${SKILL_DESCRIPTION}
+---
+
+${PROTOCOL_BODY}`;
+/** The Codex prompt file is the same body with no frontmatter. */
+const PROMPT_TEXT = PROTOCOL_BODY;

package/dist/workflows.js

@@ -0,0 +1,68 @@
+async function read(query, subject) {
+    const { data, error } = await query;
+    if (error)
+        throw new Error(`could not read ${subject}: ${error.message}`);
+    return data ?? [];
+}
+/**
+ * A workflow, its stages in order, and the exits off them.
+ *
+ * SORTED HERE RATHER THAN TRUSTED, which is the web reader's own rule: order is
+ * the whole point of a workflow, positions are deliberately not unique (a
+ * reorder rewrites the set), and a tie has to break the same way twice.
+ *
+ * FOUR READS RATHER THAN ONE EMBED. `cliv2_workflow_stages_in_workflow` carries
+ * two foreign keys into `cliv2_workflow_stages` (`stage_id` and
+ * `loop_to_stage_id`), so a nested embed of the stage document would need
+ * disambiguating by constraint name — a coupling to a constraint's spelling for
+ * the sake of saving a round trip on a tool call an agent makes once.
+ */
+export async function readWorkflow(client, workflowId) {
+    const found = await read(client.from('cliv2_workflows').select('id, name, description, ending').eq('id', workflowId), `workflow ${workflowId}`);
+    if (found.length === 0) {
+        throw new Error(`could not read workflow ${workflowId}: there is no such row, or it is not yours`);
+    }
+    const row = found[0];
+    const [links, exits] = await Promise.all([
+        read(client.from('cliv2_workflow_stages_in_workflow').select('stage_id, position')
+            .eq('workflow_id', workflowId), `the stages of workflow ${workflowId}`),
+        read(client.from('cliv2_workflow_stage_exits').select('stage_id, to_stage_id, condition, position')
+            .eq('workflow_id', workflowId), `the exits of workflow ${workflowId}`),
+    ]);
+    const ordered = [...links].sort((a, b) => a.position - b.position || a.stage_id.localeCompare(b.stage_id));
+    const stageRows = ordered.length === 0 ? [] : await read(client.from('cliv2_workflow_stages').select('id, name, description, body')
+        .in('id', ordered.map((link) => link.stage_id)), `the stage documents of workflow ${workflowId}`);
+    const byId = new Map(stageRows.map((stage) => [stage.id, stage]));
+    return {
+        id: row.id,
+        name: row.name,
+        description: row.description ?? '',
+        /* Defaulted here as well as in the column, for the web reader's reason: a
+           workflow written before the ending existed reads back as 'end'. */
+        ending: row.ending ?? 'end',
+        stages: ordered.map((link) => {
+            const stage = byId.get(link.stage_id);
+            /* A LISTED STAGE THAT DID NOT COME BACK IS AN ERROR, NEVER A GAP. The
+               join cascades on delete and archiving is not deletion, so this cannot
+               happen through the product — and a stage silently missing from the
+               middle of a recipe would be a different process presented as this one. */
+            if (!stage) {
+                throw new Error(`could not read the stage documents of workflow ${workflowId}: stage ${link.stage_id} `
+                    + 'is in the workflow but its document did not come back');
+            }
+            return {
+                id: stage.id,
+                name: stage.name,
+                description: stage.description ?? '',
+                body: stage.body ?? '',
+            };
+        }),
+        exits: [...exits]
+            .sort((a, b) => a.position - b.position || a.to_stage_id.localeCompare(b.to_stage_id))
+            .map((exit) => ({
+            stageId: exit.stage_id,
+            toStageId: exit.to_stage_id,
+            condition: exit.condition,
+        })),
+    };
+}

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@ctrl-spc/cs",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "CTRL+SPC — minimal, reliable per-machine agent presence. Sign-in, auto-start, agent detection, heartbeat presence, and ping acknowledgement.",
   "engines": {
     "node": ">=22"
   },
   "type": "module",
   "bin": {
-    "cs": "dist/index.js",
-    "cs3": "dist/panel3/cli.js"
+    "cs": "dist/index.js"
   },
   "files": [
     "dist"