@ctrl-spc/cs 0.7.1 → 0.7.2

package/dist/panel3/tools.js

@@ -105,7 +105,7 @@
  * agent naming something out of its reach stops nothing and is told so.
  *
  * ═══ AND THE KILL IS STILL THE DAEMON'S. ═══ The record is the intent, exactly
- * as it is for the person's own Stop: `cs3 run` kills the processes of stopped
+ * as it is for the person's own Stop: `panel3/cli.js run` kills the processes of stopped
  * runs on its own machine, on the poll it already has. Nothing here waits for
  * that, and nothing here claims it has happened.
  */
@@ -122,7 +122,7 @@ import { rememberSecret, redactArgs } from './secrets.js';
 import { workBrief } from './prompt.js';
 import { listCodebases } from '../codebases.js';
 import { readWorkflow } from '../workflows.js';
-import { ASK_CONTENT_COLUMNS, attachmentLine, loadAttachments, withAskContent, } from './show.js';
+import { ASK_CONTENT_COLUMNS, attachmentLine, gitRulesFor, loadAttachments, setMainBranch, withAskContent, } from './show.js';
 // ---------------------------------------------------------------------------
 // READING AND WRITING. Every query goes through the same guard every other v3
 // command uses, so a failed read can never reach an agent as an empty list.
@@ -342,6 +342,48 @@ const DECIDING = {
         + 'for free_text. A SUGGESTION, NOT A BALLOT — the person may always answer in their own words '
         + 'instead, so offer what you would act on rather than every possibility.'),
 };
+// ---------------------------------------------------------------------------
+// PROJECT CONTEXT (19/project-context-7b). `public.project_documents` — the
+// reference a team writes in the web app: architecture, design notes, how a
+// subsystem came to be the way it is. Read when the work needs it, at every
+// level, and ADDED TO by the levels that do the work.
+//
+// ═══ IT IS NOT THE SAME TABLE AS THE STANDING RULES, AND THAT IS THE POINT.
+// ═══ `public.agent_instructions` is an OBLIGATION and arrives in the prompt,
+// whole, before an agent acts; no tool here reads or writes it, at any level. A
+// reference an agent chooses to read and a mandate it is handed are two
+// different things, and the schema keeps them apart so a tool cannot confuse
+// them (see 20260919090000_agent_instructions.sql).
+/**
+ * ═══ THE READ IS BOUNDED, AND IT SAYS WHEN IT BOUNDED SOMETHING. ═══
+ *
+ * `project_documents.content` is unbounded `text` and a project may hold any
+ * number of documents, so an unbounded read would put a team's whole corpus into
+ * the same window the mandatory standing-rules block needs — and would do it
+ * silently. There is no existing row or byte limit anywhere in this file to
+ * inherit: `mcp.ts` has one of the right shape, and conventions.md rule 2 forbids
+ * `panel3/` to import it.
+ *
+ * TWO BOUNDS RATHER THAN ONE, because they catch different shapes: many small
+ * documents, and one enormous one. Whichever bites, the response ends by saying
+ * how many documents it did not show and how to ask for fewer — a truncation
+ * nobody is told about reads as a project with nothing else written down, which
+ * is worse than the read failing.
+ */
+const CONTEXT_DOCUMENT_ROWS = 50;
+const CONTEXT_DOCUMENT_CHARACTERS = 60000;
+/**
+ * Which project the caller's card is filed under, or null when it has none.
+ *
+ * `panel3_cards.project_id` IS NULLABLE and a record-only card genuinely has no
+ * project, so null is a fact rather than a failure and each caller words its own
+ * refusal. A failed READ throws through `rows`, which is a different thing again
+ * and must never be flattened into "no project".
+ */
+async function projectOfCard(caller) {
+    const cards = await rows(caller.client.from('panel3_cards').select('project_id').eq('id', caller.cardId), 'read', `the project for card ${caller.cardId}`);
+    return cards[0]?.project_id ?? null;
+}
 const ALL = [1, 2, 3];
 const line = (...parts) => parts.filter(Boolean).join('  ');
 const listed = (items, empty) => (items.length === 0 ? empty : items.join('\n'));
@@ -906,6 +948,85 @@ const TOOLS = [
             ].join('\n');
         },
     },
+    {
+        name: 'get_project_context',
+        /* ALL THREE, straight off ux.md's "Who gets what" table, where
+           `get_project_context` has always sat in the "Read the record" row. Reading
+           what a team has written down is not a privilege any level is denied. */
+        levels: ALL,
+        description: 'The documentation this project\'s team has written: architecture, design notes, conventions, '
+            + 'how a subsystem came to be the way it is. Read it when the work needs it — before you '
+            + 'design something, before you follow a convention you are guessing at, and before you tell '
+            + 'the person how this project does something. Pass a codebase id to get that codebase\'s own '
+            + 'documents as well as the project\'s.',
+        input: {
+            codebase_id: z.string().uuid().optional().describe('A registered project codebase, to get its OWN documents alongside the project-wide ones. '
+                + 'Leave it out for the project-wide documents alone.'),
+        },
+        handler: async (caller, args) => {
+            const { codebase_id } = args;
+            const projectId = await projectOfCard(caller);
+            if (!projectId) {
+                return 'This conversation is not filed under a project, so there is no project context to read.';
+            }
+            const scoped = caller.client
+                .from('project_documents')
+                .select('id, title, type, codebase_id, content')
+                .eq('project_id', projectId);
+            const documents = await rows((codebase_id === undefined
+                ? scoped.is('codebase_id', null)
+                : scoped.or(`codebase_id.is.null,codebase_id.eq.${codebase_id}`))
+                /* MOST SPECIFIC FIRST, the order ux.md gives for the two scopes: a
+                   codebase's documents beat the project's for work in that codebase,
+                   so they are read first and are the ones that survive the bound. */
+                .order('codebase_id', { nullsFirst: false })
+                .order('created_at')
+                /* ONE MORE THAN THE CAP, so "there are more" is something this read
+                   OBSERVED rather than something it assumed from a full page. The
+                   extra row is never rendered; it only makes the closing line honest,
+                   and it is why the count below is "at least". */
+                .limit(CONTEXT_DOCUMENT_ROWS + 1), 'read', `the project context on project ${projectId}`);
+            const withinRows = documents.slice(0, CONTEXT_DOCUMENT_ROWS);
+            const pastRowCap = documents.length > CONTEXT_DOCUMENT_ROWS;
+            /* THE CHARACTER WALK. The first document is always included whatever its
+               size: a project whose one document is larger than the whole budget must
+               still get an answer, and truncating a document's BODY would hand an
+               agent half a convention with no sign of where it stopped. */
+            const shown = [];
+            let used = 0;
+            for (const document of withinRows) {
+                if (used + document.content.length > CONTEXT_DOCUMENT_CHARACTERS && shown.length > 0)
+                    break;
+                shown.push(document);
+                used += document.content.length;
+            }
+            if (shown.length === 0) {
+                return codebase_id === undefined
+                    ? 'This project has no context documents yet.'
+                    : 'This project and that codebase have no context documents yet.';
+            }
+            const cut = withinRows.length - shown.length;
+            return [
+                ...shown.flatMap((document) => [
+                    `--- ${document.title}  (${document.type}${document.codebase_id === null ? ', project' : ', this codebase'})  id ${document.id} ---`,
+                    document.content,
+                    '',
+                ]),
+                /* ═══ SAID WHENEVER SOMETHING WAS LEFT OUT, AND NEVER OTHERWISE. ═══ A
+                   complete answer that ends by discussing its own limits teaches an
+                   agent to distrust a read that was fine. */
+                ...(cut > 0 || pastRowCap
+                    ? [
+                        `NOT EVERYTHING IS ABOVE: at least ${cut + (pastRowCap ? 1 : 0)} more `
+                            + `${cut + (pastRowCap ? 1 : 0) === 1 ? 'document was' : 'documents were'} not shown. `
+                            + `This read is capped at ${CONTEXT_DOCUMENT_ROWS} documents and `
+                            + `${CONTEXT_DOCUMENT_CHARACTERS} characters, and the most specific documents come `
+                            + 'first. Ask again without a codebase, or for one codebase at a time, to narrow it.',
+                    ]
+                    : []),
+            ].join('\n');
+        },
+    },
     {
         name: 'list_cards',
         /* ═══ LEVEL 1 ONLY, AND THIS OVERRIDES plan.md's TABLE. ═══ The plan grants
@@ -1032,6 +1153,136 @@ const TOOLS = [
     // the placement tools. Editing an item as the work moves, and producing an
     // object, are two other rows of that same table and they are NOT level 1's:
     // see the next section, which is where they now live.
+    /**
+     * ═══ THE ANSWER TO THE ONE GIT QUESTION A PERSON IS EVER ASKED. ═══
+     *
+     * worktrees-8, story 3: a codebase whose base branch is genuinely ambiguous is
+     * settled by asking the person ONCE, and the answer is stored on the CODEBASE
+     * rather than on the card that prompted it, so nobody is asked twice.
+     *
+     * A TOOL RATHER THAN A SIDE EFFECT OF THE ANSWER, for two reasons. The answer
+     * has to land on the codebase and an ask lands on a card. And the only other
+     * route is teaching the questions surface to write a settings table, which
+     * would couple two things that have no reason to know each other.
+     *
+     * LEVEL 1 ONLY. It is the coordinator that sees across cards, that holds
+     * `ask_question`, and that needs the fact before it dispatches. A level 2 or 3
+     * agent asking would be asking about a card, mid-work, having already started
+     * in the wrong place.
+     */
+    {
+        name: 'set_main_branch',
+        levels: [1],
+        description: 'Record which branch finished work in a codebase should go back to. Use this ONLY after asking '
+            + 'the person and getting an answer: it is the organization\'s setting, it applies to every '
+            + 'member and every future card in that codebase, and nobody is asked again. Never guess it, '
+            + 'and never call this to change a branch somebody already set.',
+        input: {
+            codebase_id: z.string().describe('The codebase id, as the codebase list gave it to you.'),
+            branch: z.string().min(1).describe('The branch name exactly as the person chose it.'),
+        },
+        handler: async (caller, args) => {
+            const { codebase_id, branch } = args;
+            /* THROUGH `show.ts`, WHICH IS THE ONE FILE UNDER panel3/ THAT MAY NAME
+               THIS TABLE. conventions.md records why, and
+               panel3-isolation.contract.test.mjs pins it: reads and writes alike go
+               through one file, so a grep for the table finds every caller. */
+            await setMainBranch(caller.client, codebase_id, branch);
+            return `Work in that codebase now starts from ${branch} and goes back to it. `
+                + 'Nobody will be asked again.';
+        },
+    },
+    /**
+     * ═══ THE AGENT ASKS FOR THE OFFER; THE PRODUCT WRITES IT. ═══
+     *
+     * worktrees-8 C1. `ask_question`'s options are typed by a model out of prose,
+     * so any product rule that reads them back is a rule about transcription. This
+     * tool carries ONE agent-typed string, `what_was_done`, and nothing is ever
+     * compared against it: the question, both answers and the merge itself are the
+     * product's, exactly as an artifact approval already is.
+     *
+     * ═══ IT READS STAMPS, IT DOES NOT RESOLVE ANYTHING. ═══ `branch` and `base`
+     * were written by `cardWorktree` precisely so a second reader would not
+     * re-implement the derivation. No git runs here.
+     */
+    {
+        name: 'offer_ending',
+        /* ═══ LEVEL 2 ONLY, AND THE DATABASE RECHECKS THAT IT IS THE OWNER. ═══
+           Level 1 never holds a card's branch, and level 3 has no ending and does
+           not speak to the person. */
+        levels: [2],
+        description: 'Offer the person the ending for this card: put the finished work onto the main branch, or '
+            + 'leave it on its branch. Call this when the card\'s work is DONE and the codebase lands on '
+            + 'the main branch. You do not write the question or the answers and you never merge anything: '
+            + 'the product composes both, and it performs the merge itself if they choose to put the work '
+            + 'back. Say in one sentence what was done, in their words. After this call, stop immediately: '
+            + 'you are started again with what the product did with their answer.',
+        input: {
+            what_was_done: z.string().min(1).describe('One sentence, in the person\'s words, saying what this card\'s work actually changed. It is '
+                + 'the only part of the offer you write.'),
+        },
+        handler: async (caller, args) => {
+            const { what_was_done } = args;
+            const { client, runId, processToken } = caller;
+            if (!caller.isOwner || processToken === undefined) {
+                throw new Error('NOTHING WAS WRITTEN. Only this card\'s current conversation owner can offer the ending.');
+            }
+            if (what_was_done.length > PERSON_READS_LIMIT) {
+                throw new Error(`NOTHING WAS WRITTEN and nobody was asked: that is ${what_was_done.length} characters and `
+                    + `they read it on a card three inches wide. The limit is ${PERSON_READS_LIMIT}. One `
+                    + 'sentence saying what changed.');
+            }
+            const run = await only(client.from('panel3_runs')
+                .select('codebase_id, branch, base, card:panel3_cards!panel3_runs_card_id_fkey(project_id)')
+                .eq('id', runId), 'read', 'which branch this card\'s work is on');
+            if (!run.codebase_id || !run.branch || !run.base || !run.card?.project_id) {
+                throw new Error('NOTHING WAS WRITTEN. This card has no codebase, branch and base recorded, so there is no '
+                    + 'ending to offer. Say what you did and finish the card.');
+            }
+            const rules = await gitRulesFor(client, run.codebase_id, run.card.project_id);
+            if (rules.landing !== 'main') {
+                throw new Error('NOTHING WAS WRITTEN. Finished work in this codebase does not go onto the main branch, so '
+                    + 'there is no ending to offer. Say where the work is and finish the card.');
+            }
+            const [ask] = await rows(client.rpc('panel3_ask', {
+                p_run_id: runId,
+                /* THE QUESTION AND THE CONTEXT ARE COMPOSED HERE, from the two stamps,
+                   which is why story 4's scenario can promise the branch and the
+                   separation are in it. The agent's sentence is appended to the
+                   context and decides nothing. */
+                p_question: `Put this work onto ${run.base}?`,
+                p_category: 'Finished work',
+                p_context: `The work on this card is finished and is on branch ${run.branch}, in a copy of its own, `
+                    + 'apart from anything else working in this codebase on this computer. '
+                    + what_was_done,
+                /* ═══ PASSED AND THEN IGNORED, AND BOTH HALVES ARE DELIBERATE. ═══ The
+                   statement overwrites the mode and the options with the product's own
+                   when `p_offers_landing` is true, which is where they are enforced.
+                   They are named here only because the twelve-argument core carries no
+                   defaults, so PostgREST resolves the overload by the exact argument
+                   set it is given. */
+                p_answer_mode: 'single_select',
+                p_options: [],
+                p_question_id: null,
+                p_work_item_id: null,
+                p_ask_person: true,
+                p_process_token: processToken,
+                p_related_artifact_id: null,
+                p_offers_landing: true,
+            }), 'put', 'the ending where it can be answered');
+            if (!ask || ask.ask_id === null) {
+                throw new Error(`NOTHING WAS WRITTEN and nobody was asked: run ${runId} has already ended, or a question `
+                    + `is already waiting on you${ask?.held_question ? ` (${ask.held_question})` : ''}. Deal `
+                    + 'with that first.');
+            }
+            return [
+                `The ending is with the person now, id ${ask.ask_id}. They were asked whether this work `
+                    + `should go onto ${run.base}, with the product's own two answers.`,
+                'YOU HAVE STOPPED. Do not merge anything and do not finish the card: when they answer, you',
+                'are started again and told what the product did.',
+            ].join('\n');
+        },
+    },
     {
         name: 'create_epic',
         levels: [1],
@@ -1198,6 +1449,77 @@ const TOOLS = [
             return `Updated artifact ${artifact.title ?? artifact.id}.`;
         },
     },
+    {
+        name: 'add_project_context',
+        /* ═══ THE LEVELS THAT DO THE WORK, AND ux.md IS AMENDED RATHER THAN ARGUED
+           PAST. ═══ A context document is a PRODUCED OBJECT, not board structure, so
+           it does not fall under "product structure is level 1's alone"; and the
+           levels that do the work are the levels that learn something worth keeping,
+           while level 1 launches and exits. ux.md's "Who gets what" table carries
+           this ruling, and `panel3-tools.contract.test.mjs` pins all three lists to
+           it exhaustively. */
+        levels: [2, 3],
+        /* ═══ ADD, AND NEVER CHANGE OR REMOVE. ═══ `project_documents` has no
+           history, no version UI and no DELETE policy — hard delete is unreachable
+           rather than merely un-surfaced. That was safe while no agent could write
+           these rows at all. An agent UPDATE would permanently overwrite a person's
+           own text with nothing to restore from, policed only by a sentence in a
+           description. So the tool adds and never changes, and the name says so
+           rather than the description having to. */
+        description: 'Write one new document into this project\'s context — the reference the team keeps for work '
+            + 'like this. Use it when the conversation SETTLES something the project should keep: a '
+            + 'convention agreed, how a subsystem actually fits together, why an approach was rejected. '
+            + 'It adds a document and never changes or removes one, so do not use it to correct something '
+            + 'already written; say what is wrong in your report instead. Not for the work you were sent '
+            + 'to do — that goes in an artifact on the work item.',
+        input: {
+            title: z.string().min(1).max(100).describe('What this document is, in a few words a teammate would search for. 100 characters at most.'),
+            type: z.enum(['instructions', 'architecture', 'design', 'conventions', 'other']).describe('Which kind of reference this is, matching the five the web app offers.'),
+            content: z.string().min(1).describe('The document itself, in markdown, complete. It is read by people and by agents on later '
+                + 'work, neither of whom has seen this conversation.'),
+            scope: z.enum(['project', 'codebase']).optional().describe('`codebase` files it under the codebase you are working in, for something true of that repo '
+                + 'and no other. Defaults to `project`, which every codebase inherits.'),
+        },
+        handler: async (caller, args) => {
+            const a = args;
+            /* ═══ THE PROJECT COMES OFF THE RUN'S OWN CARD, NEVER OFF AN ARGUMENT.
+               ═══ There is no `project_id` input, deliberately: RLS is org-scoped, so
+               a card in one project could otherwise write a document into a sibling
+               project in the same organization, and nothing about that would look like
+               a mistake afterwards. */
+            const projectId = await projectOfCard(caller);
+            if (!projectId) {
+                throw new Error('NOTHING WAS WRITTEN: this conversation is not filed under a project, so there is no '
+                    + 'project context to add to. Put what you learned in your report instead.');
+            }
+            let codebaseId = null;
+            if (a.scope === 'codebase') {
+                /* THE RUN'S OWN CODEBASE, AND NO OTHER, for the same reason the project
+                   is not an argument. A level 2 owner on a record-only card has none,
+                   and that is a refusal rather than a silent fall back to project
+                   scope: filing a codebase-specific note project-wide puts it in front
+                   of work it does not apply to. */
+                const runs = await rows(caller.client.from('panel3_runs').select('codebase_id').eq('id', caller.runId), 'read', `the codebase run ${caller.runId} belongs to`);
+                codebaseId = runs[0]?.codebase_id ?? null;
+                if (!codebaseId) {
+                    throw new Error('NOTHING WAS WRITTEN: this work is not attached to a codebase, so it has no codebase '
+                        + 'to file a document under. Call this again with scope `project` if it holds for the '
+                        + 'whole project.');
+                }
+            }
+            const document = await only(caller.client.from('project_documents').insert({
+                project_id: projectId,
+                codebase_id: codebaseId,
+                title: a.title.trim(),
+                type: a.type,
+                content: a.content,
+            }).select('id, title'), 'write', 'a project context document');
+            return (`Written. "${document.title}" is in this project's context now, id ${document.id}`
+                + `${codebaseId === null ? '' : ', filed under this codebase'}. `
+                + 'The person will find it under Project settings. You cannot change or remove it, so if it '
+                + 'needs correcting, say so rather than writing a second one.');
+        },
+    },
     // ── Say something now ────────────────────────────────────────────────────
     //
     // ═══ LEVEL 2 ONLY, AND THE DATABASE IS WHAT ENFORCES IT. ═══ `panel3_say`
@@ -1500,8 +1822,7 @@ const TOOLS = [
             }
             let codebase = null;
             if (codebase_id) {
-                const cards = await rows(caller.client.from('panel3_cards').select('project_id').eq('id', caller.cardId), 'read', `the project for card ${caller.cardId}`);
-                const projectId = cards[0]?.project_id;
+                const projectId = await projectOfCard(caller);
                 if (!projectId) {
                     throw new Error('This conversation is not filed under a project, so it has no codebase to use.');
                 }
@@ -1632,7 +1953,7 @@ async function receipt({ client, runId, cardId }, kind, refId, label) {
     await only(client.from('panel3_outputs').insert({ card_id: cardId, run_id: runId, kind, ref_id: refId, label }).select('id'), 'record', `the ${kind} on the card`);
 }
 /** The names one level is served, in the order they are registered. Exported for
- *  the same reason `cs3 show` exists: a rule nobody can print is a rule nobody
+ *  the same reason `cs show` exists: a rule nobody can print is a rule nobody
  *  can check. */
 export function toolNamesForLevel(level, isOwner = false) {
     return TOOLS.filter((t) => t.levels.includes(level) && !(isOwner && t.name === 'escalate'))

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/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@ctrl-spc/cs",
-  "version": "0.7.1",
+  "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"