@ctrl-spc/cli 1.1.15 → 1.2.1

package/dist/presence.js

@@ -0,0 +1,62 @@
+import { REALTIME_SUBSCRIBE_STATES } from '@supabase/supabase-js';
+function channelName(projectId) {
+    return `presence:project:${projectId}`;
+}
+/**
+ * Opens the Realtime presence channel for `payload.projectId`, tracked
+ * under `payload.machineId`. A stable per-machine key keeps two machines for
+ * the same user visible at once without leaking local checkout paths.
+ * Tracking only starts once the
+ * channel reports `SUBSCRIBED`; `setWorking`/`setAvailable` re-track the
+ * updated payload immediately if already subscribed, or lazily once it is.
+ */
+export function startPresence(client, payload) {
+    const channel = client.channel(channelName(payload.projectId), {
+        config: { presence: { key: payload.machineId } },
+    });
+    let current = { ...payload };
+    let subscribed = false;
+    // Serializes track() calls on this channel so a burst of
+    // setWorking/setAvailable flips can never have two in flight at once —
+    // each one lands before the next is sent.
+    let trackChain = Promise.resolve();
+    function enqueueTrack(next) {
+        trackChain = trackChain.then(() => channel.track(next));
+    }
+    channel.subscribe((status, err) => {
+        if (status === REALTIME_SUBSCRIBE_STATES.SUBSCRIBED) {
+            subscribed = true;
+            enqueueTrack(current);
+        }
+        else if (status === REALTIME_SUBSCRIBE_STATES.CHANNEL_ERROR ||
+            status === REALTIME_SUBSCRIBE_STATES.TIMED_OUT) {
+            // Reconnection is supabase-js's default behavior (Global Constraints);
+            // this is visibility only, so a broken presence connection doesn't
+            // fail silently behind the "Presence: available" line already printed
+            // at startup.
+            console.warn(`Presence channel ${status.toLowerCase()}${err ? `: ${err.message}` : ''} — will retry.`);
+        }
+    });
+    function retrack(next) {
+        current = next;
+        if (subscribed)
+            enqueueTrack(current);
+    }
+    return {
+        setWorking(taskId, agent) {
+            retrack({ ...current, status: 'working', workingOnTaskId: taskId, workingAgent: agent });
+            console.log(`Presence: working on ${taskId}`);
+        },
+        setAvailable() {
+            retrack({ ...current, status: 'available', workingOnTaskId: undefined, workingAgent: undefined });
+            console.log('Presence: available');
+        },
+        async stop() {
+            // Let any in-flight track() finish first so it can't land after (and
+            // undo) the untrack below.
+            await trackChain.catch(() => { });
+            await channel.untrack();
+            await client.removeChannel(channel);
+        },
+    };
+}

package/dist/prompt.js

@@ -0,0 +1,47 @@
+import { createInterface } from 'node:readline/promises';
+/**
+ * Prompts for free-text input with a default. When stdin isn't a TTY
+ * (scripted/non-interactive use — including our own manual verification
+ * runs) the default is returned without prompting.
+ */
+export async function ask(question, defaultValue) {
+    if (!process.stdin.isTTY)
+        return defaultValue;
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question(`${question} [${defaultValue}]: `)).trim();
+        return answer || defaultValue;
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Prompts for a numbered selection from `choices`. When stdin isn't a TTY,
+ * or there's only one choice, `choices[defaultIndex]` is returned without
+ * prompting.
+ */
+export async function select(question, choices, defaultIndex = 0) {
+    if (choices.length === 0)
+        throw new Error('select() requires at least one choice');
+    const clampedDefault = Math.min(Math.max(defaultIndex, 0), choices.length - 1);
+    if (!process.stdin.isTTY || choices.length === 1)
+        return choices[clampedDefault].value;
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        console.log(question);
+        choices.forEach((choice, i) => {
+            console.log(`  ${i + 1}) ${choice.label}${i === clampedDefault ? ' (default)' : ''}`);
+        });
+        const answer = (await rl.question(`Choice [${clampedDefault + 1}]: `)).trim();
+        if (!answer)
+            return choices[clampedDefault].value;
+        const idx = Number.parseInt(answer, 10) - 1;
+        if (Number.isInteger(idx) && idx >= 0 && idx < choices.length)
+            return choices[idx].value;
+        return choices[clampedDefault].value;
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/protocol.js

@@ -0,0 +1,136 @@
+/**
+ * §5a protocol text, kept in sync with the installed Claude/Codex skill. Two
+ * forms, matching the spec's "delivered redundantly" design:
+ *
+ *  - `PROTOCOL_FULL`: the complete section, served by the `ctrl-spc-protocol`
+ *    MCP prompt (spec §5: "MCP prompt: ctrl-spc-protocol — the full §5a
+ *    protocol text, referenced by the installed skill").
+ *  - `PROTOCOL_SHORT`: a compact restatement embedded in every `get_task`
+ *    response (spec §5: "a compact restatement of the working protocol
+ *    (§5a), so even a session that skipped the skill gets the rules").
+ */
+export const PROTOCOL_FULL = `## 5a. Agent working protocol
+
+Delivered redundantly (installed skill + MCP), phrased imperatively for the agent:
+
+**HARD STOP — unclear novel feature.** After \`record_context_exploration\` succeeds,
+if the task does not explicitly request a build or name a deliverable, the immediate
+next tool call is \`ask_question\` with category \`intent\` and the exact question:
+“What should I produce for this feature? Select one or more: build, plan, spec,
+diagram, mock, wireframe.” Then call \`end_work\` with reason
+\`pending_user_answer\` and outcome \`blocked\`. Do not call \`get_task\` again,
+\`update_task\`, \`create_artifact\`, \`reserve_work_paths\`, or any intervening tool.
+The context artifact is the only artifact allowed before the answer. A read-only
+execution sandbox is not a missing checkout and never changes this intent question.
+Multiple selections are allowed.
+
+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 persistence and
+before the intent question, either say nothing or 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.** \`/ctrl-spc work <id>\` → call \`get_task(id)\` before
+   anything else. \`get_task\` is read-only: it does not change task status, presence,
+   collaboration, claims, or reservations. The ID is the only context in the paste;
+   everything current lives in ctrl-spc.
+2. **Begin explicitly.** Read every active repository scope, checkout, topology revision,
+   unmet dependency, and collaborator, then call \`begin_work\`. The first live run
+   becomes coordinator and \`begin_work\` moves a Backlog item to In Progress. Later runs
+   join as collaborators without repeating that transition. Only the current coordinator
+   may make later task-status changes, and no agent marks an item Done autonomously.
+3. **Repair missing context.** If \`begin_work\` reports unavailable checkouts, warn the
+   user and offer to fetch or link each repository. Never fetch without approval. If the
+   user explicitly continues without one, call \`acknowledge_unavailable_checkout\` with a
+   reason. After every missing scope is fetched or acknowledged, call \`begin_work\` again.
+   Acknowledgement records a limitation; it never pretends the repository was reviewed.
+4. **Delegate exploration; never substitute direct exploration.** Every pasted work item
+   MUST use at least one read-only subagent. After \`begin_work\` joins, create a coverage
+   queue and partition every available repository scope exactly once across bounded
+   subagent invocations. Every child prompt explicitly lists its assigned
+   \`repository_scope_ids\`; across the batch each available ID appears exactly once. If
+   using Codex \`spawn_agent\`, MUST pass \`fork_turns: "none"\`; never pass \`all\` or a
+   recent-turn count. Each assignment is self-contained and includes only the exact scope
+   IDs, checkout paths, inspection focus, read-only restrictions, and required report
+   shape. Never include or inherit the parent \`/ctrl-spc work\` command. A context child
+   never calls ctrl-spc tools—including \`get_task\` or \`begin_work\`—and never picks up
+   the work item; it only inspects its assigned paths and returns its report.
+   If
+   zero scopes are available after explicit acknowledgements, one child
+   inspects the task/artifact context and reports the unavailable scopes without pretending
+   they were reviewed. Children inspect only: no file mutation, path reservation, mutating
+   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 the reports are persisted. Each report uses
+   \`{ agent, focus, repository_scope_ids, inspected_paths, findings, likely_impact,
+   unresolved_questions }\`; artifact coverage remains separate.
+   If the client cannot start a subagent, do not inspect directly, plan, ask task questions,
+   reserve, or edit. Call \`record_context_exploration\` with
+   \`blocked_reason = subagents_unavailable\`, tell the user, and stop.
+5. **Persist exploration before any decision.** The parent consolidates every child report
+   and MUST call \`record_context_exploration\` before deciding the action, asking a task
+   question, planning, reserving, or editing. This creates an analysis artifact on the work
+   item and covers every active scope exactly once; unavailable scopes carry the current
+   run acknowledgement ID. 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. **Infer explicit work; otherwise ask exactly what is needed.** After exploration is
+   recorded, classify intent from the work item's explicit wording and accepted answers,
+   never from the exploration findings. Findings do not turn an unclear request into an
+   authorized deliverable. Perform the action only when the item explicitly names it; do
+   not ask for confirmation. Otherwise use \`ask_question\`. 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 immediate next call is the exact build/plan/spec/diagram/mock/wireframe
+   \`ask_question\`.
+   Generic goals such as “improve,” “coordinate,” “prepare,” or “support” do not authorize
+   analysis, a release decision, implementation, or another artifact. In this state do not
+   call \`update_task\`, \`create_artifact\`, \`reserve_work_paths\`, or \`create_task\`; do not
+   decide, edit, or mark the run completed. The context-exploration analysis artifact is the
+   only output allowed before the user's answer.
+   Also 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\`, a receipt outcome of \`blocked\`, the
+   final task revision, and every live artifact ID; continue only in a later pasted run.
+7. **Persist every accepted answer and durable finding.** Immediately call \`update_task\`
+   to add accepted decisions, constraints, acceptance criteria, and durable findings to the
+   description. Use the latest \`get_task\` revision; refetch and reconcile on conflict.
+   Never leave an accepted answer or finding only in terminal, chat, or a subagent report.
+8. **Reserve the exact write surface.** Before editing, call \`reserve_work_paths\` with
+   the topology revision and, for every intended edit, the exact
+   \`repository_scope_id\`, selected \`repository_checkout_id\`, repo-relative path, and
+   write mode. An empty path reserves the entire scope. Do not edit until the full atomic
+   request succeeds, and edit only the checkout + paths returned as reserved.
+9. **Never edit through a collision.** A collision reserves nothing. Narrow to disjoint
+   paths, wait, ask for an explicit handoff, or use an isolated Git worktree. Never edit a
+   conflicting path, overwrite unexpected local changes, or assume another agent stopped.
+10. **Persist every substantive non-question output.** Use \`create_artifact\` for every
+   plan, specification, research/finding report, schema, diagram, mock, and wireframe before
+   presenting it as complete. Use type \`analysis\` for research/findings, \`plan\` for plans,
+   \`spec\` for specifications or proposed schemas, and the matching visual type. Never
+   write planning documents into a repository. Every artifact has exactly one coverage disposition and non-empty
+   reason for every active repository scope at the current topology revision.
+11. **Keep the work item self-sufficient.** Questions are durable records created through
+   \`ask_question\`; accepted answers and durable facts live in the description; substantive
+   outputs live in artifacts. No progress comments. Never leave useful
+   context only in terminal, chat history, a subagent report, or a repository planning file.
+   If work is too large, ask through \`ask_question\`; after approval use \`create_task\` to
+   create dependency-linked items with a shared feature tag and matching board order.
+12. **Release and 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\` exactly matches every live artifact produced by this run and includes
+   the context-exploration artifact. Use \`completed\` only for finished work, \`blocked\`
+   for a persisted question or unavailable subagents, and \`aborted\` only when intentionally
+   abandoning the run. Missing, stale, foreign, duplicate, or incomplete receipts are
+   rejected. Ending releases only this session's work.`;
+export const PROTOCOL_SHORT = 'ctrl-spc protocol (compact — full text: MCP prompt `ctrl-spc-protocol`): ' +
+    'HARD STOP unclear novel feature: immediately after record_context_exploration, ask_question category intent exactly “What should I produce for this feature? Select one or more: build, plan, spec, diagram, mock, wireframe.” Then end_work blocked pending_user_answer. No intervening get_task/update_task/create_artifact/reservation/tool; read-only sandbox is not a missing checkout. ' +
+    '1) get_task is read-only; begin_work (run coordinator); resolve missing checkouts via fetch/link or acknowledge_unavailable_checkout. ' +
+    '2) Every item needs read-only subagents covering scope IDs once. Codex spawn_agent MUST use fork_turns:none; its self-contained prompt has exact IDs/paths/focus, no copied command. Child calls no ctrl-spc tools and writes nothing. If unavailable, record blocked; stop. ' +
+    '3) Parent must record_context_exploration before deciding, asking, planning, reserving, or editing. Before success narrate process only—no findings/conclusions/impact/decisions. Later summaries add no unpersisted facts. ' +
+    '4) Intent only from task/accepted answers, never findings; improve/coordinate/prepare/support are not deliverables. Unclear novel feature: next mutation after context MUST be ask_question for build/plan/spec/diagram/mock/wireframe. No update_task/create_artifact/reservation/decision/edit before answer; end blocked pending_user_answer. Bugs ask only missing repro/expected/actual. ' +
+    '5) Put every accepted answer and durable finding in the description via revision-safe update_task; use create_artifact for every substantive non-question output with coverage for every active scope. No progress comments or terminal-only findings. ' +
+    '6) reserve_work_paths exact checkout+paths; never edit collisions. release_work_paths, then end_work with persistence_receipt={final_task_revision,artifact_ids,outcome}.';

package/dist/skills.js

@@ -0,0 +1,152 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+// Verbatim from the task brief — 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>.';
+const CLAUDE_MCP_PERMISSION = 'mcp__ctrl-spc__*';
+/**
+ * Home directory the skill files are written under: `CTRL_SPC_HOME` env
+ * override (used for tests and manual verification runs so they don't touch
+ * this machine's real `~/.claude` / `~/.codex`), else `os.homedir()`.
+ */
+export function resolveHome() {
+    return process.env.CTRL_SPC_HOME || homedir();
+}
+export function claudeSkillPath() {
+    return join(resolveHome(), '.claude', 'skills', 'ctrl-spc', 'SKILL.md');
+}
+export function claudeSettingsPath() {
+    return join(resolveHome(), '.claude', 'settings.json');
+}
+export function codexPromptPath() {
+    return join(resolveHome(), '.codex', 'prompts', 'ctrl-spc.md');
+}
+export function codexSkillPath() {
+    return join(resolveHome(), '.agents', 'skills', 'ctrl-spc', 'SKILL.md');
+}
+export function codexLegacySkillPath() {
+    return join(resolveHome(), '.codex', 'skills', 'ctrl-spc', 'SKILL.md');
+}
+/**
+ * The §5a protocol, summarized imperatively for an agent that just resolved
+ * `/ctrl-spc work <id>` or `/ctrl-spc artifact <id>`. The full text also
+ * lives behind the `ctrl-spc-protocol` MCP prompt; parity tests keep the
+ * native skill's deterministic gates aligned with both protocol forms.
+ */
+function protocolBody(mcpUrl) {
+    return `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:
+
+HARD STOP — unclear novel feature: 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\` and this exact question: “What should I produce for this feature? Select one or more: build, plan, spec, diagram, mock, 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.
+
+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. 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 the work item's analysis artifact before deciding what to do, asking a task question, planning, reserving, or editing. Pass the structured reports plus a separate coverage array; include every active 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 — after exploration is recorded, 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\`. 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 \`ask_question\`; it must say “select one or more: build, plan, spec, diagram, mock, wireframe.” 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 answers and findings — after every accepted answer, call \`update_task\` to add the decision, constraint, acceptance criterion, and durable findings to the description. Pass the latest revision and refetch/reconcile on conflict. Do not use progress comments; do not leave findings only in the terminal.
+8. Reserve before writing — call \`reserve_work_paths\` with the topology revision, exact checkout ID, and every repository-relative path you intend to edit. Do not edit until the full atomic request succeeds. On collision, narrow to disjoint paths, wait, ask for an explicit handoff, or use an isolated Git worktree. Never edit a conflicting path.
+9. Persist every output — every substantive non-question output must be a ctrl-spc artifact before it is presented as complete. Use \`create_artifact\` type \`analysis\` for research/findings, \`plan\` for plans, \`spec\` for specifications or proposed schemas, and the matching type for diagrams, mocks, and wireframes. Never write planning documents into a repository. Every artifact includes exactly one coverage disposition and non-empty reason for every active repository scope.
+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 are persisted through \`ask_question\`; accepted answers and durable facts live in the description; substantive outputs live in artifacts. \`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\`. Tools live at ${mcpUrl}.
+`;
+}
+function claudeSkillMarkdown(mcpUrl) {
+    return `---
+name: ctrl-spc
+description: ${SKILL_DESCRIPTION}
+---
+
+${protocolBody(mcpUrl)}`;
+}
+function codexSkillMarkdown(mcpUrl) {
+    return `---
+name: ctrl-spc
+description: ${SKILL_DESCRIPTION}
+---
+
+${protocolBody(mcpUrl)}`;
+}
+function ensureClaudeMcpPermission() {
+    const path = claudeSettingsPath();
+    let settings = {};
+    if (existsSync(path)) {
+        try {
+            const parsed = JSON.parse(readFileSync(path, 'utf8'));
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                throw new Error('root must be an object');
+            settings = parsed;
+        }
+        catch (err) {
+            throw new Error(`Could not update ${path}: invalid JSON (${err.message})`);
+        }
+    }
+    const currentPermissions = settings.permissions;
+    if (currentPermissions !== undefined && (!currentPermissions || typeof currentPermissions !== 'object' || Array.isArray(currentPermissions))) {
+        throw new Error(`Could not update ${path}: permissions must be an object.`);
+    }
+    const permissions = (currentPermissions ?? {});
+    const currentAllow = permissions.allow;
+    if (currentAllow !== undefined && !Array.isArray(currentAllow)) {
+        throw new Error(`Could not update ${path}: permissions.allow must be an array.`);
+    }
+    const allow = [...(currentAllow ?? [])];
+    // Avoid rewriting a user-owned global settings file on every ctrl-spc
+    // startup. Besides needless churn, a no-op write can trigger live config
+    // reloads in an already-running Claude session.
+    if (allow.includes(CLAUDE_MCP_PERMISSION))
+        return;
+    allow.push(CLAUDE_MCP_PERMISSION);
+    settings.permissions = { ...permissions, allow };
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true });
+    // Write beside the destination and rename into place so a crash, disk-full
+    // error, or interrupted process cannot leave settings.json half-written.
+    // Keep an existing file's permission bits; use a private mode for a new
+    // user settings file.
+    const mode = existsSync(path) ? statSync(path).mode & 0o777 : 0o600;
+    const tempPath = join(dir, `.settings.json.${process.pid}.${randomUUID()}.tmp`);
+    try {
+        writeFileSync(tempPath, `${JSON.stringify(settings, null, 2)}\n`, { encoding: 'utf8', mode });
+        chmodSync(tempPath, mode);
+        renameSync(tempPath, path);
+    }
+    catch (err) {
+        rmSync(tempPath, { force: true });
+        throw err;
+    }
+}
+/**
+ * Writes/refreshes the thin native skill for each detected agent (spec §4:
+ * "installs/refreshes the `/ctrl-spc` skill" on every start, so it never
+ * drifts from the MCP protocol). Only agents present in `agents` get a
+ * file — nothing is written for an agent that isn't installed.
+ */
+export function installSkills(agents, mcpUrl) {
+    if (agents.includes('claude')) {
+        ensureClaudeMcpPermission();
+        const path = claudeSkillPath();
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, claudeSkillMarkdown(mcpUrl), 'utf8');
+    }
+    if (agents.includes('codex')) {
+        const skillPath = codexSkillPath();
+        mkdirSync(dirname(skillPath), { recursive: true });
+        writeFileSync(skillPath, codexSkillMarkdown(mcpUrl), 'utf8');
+        const legacySkillPath = codexLegacySkillPath();
+        mkdirSync(dirname(legacySkillPath), { recursive: true });
+        writeFileSync(legacySkillPath, codexSkillMarkdown(mcpUrl), 'utf8');
+        // Keep the deprecated custom-prompt file as a compatibility fallback for
+        // users who still invoke it explicitly as `/prompts:ctrl-spc ...`.
+        const promptPath = codexPromptPath();
+        mkdirSync(dirname(promptPath), { recursive: true });
+        writeFileSync(promptPath, protocolBody(mcpUrl), 'utf8');
+    }
+}

package/dist/supabase.js

@@ -1,13 +1,43 @@
 import { createClient } from '@supabase/supabase-js';
-export const SUPABASE_URL = 'https://dxlxlphkypjjyqfgpood.supabase.co';
-export const SUPABASE_ANON_KEY = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImR4bHhscGhreXBqanlxZmdwb29kIiwicm9sZSI6ImFub24iLCJpYXQiOjE3ODAwNzcxMjEsImV4cCI6MjA5NTY1MzEyMX0.s0RkrQUqGRN45Q0lcBb_LkVEqYdYc0FKuVupzKKJrtQ';
-export const SUPABASE_FUNCTIONS_URL = `${SUPABASE_URL}/functions/v1`;
-export function createSupabaseClient() {
-    return createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
-        auth: {
-            autoRefreshToken: true,
-            detectSessionInUrl: false,
-            persistSession: false,
-        },
+import { SUPABASE_URL, SUPABASE_KEY } from './env.js';
+import { readSession, writeSession } from './config.js';
+/** Thrown by {@link getClient} when there is no usable stored session. */
+export class NotLoggedIn extends Error {
+    constructor(message = 'Not logged in. Run `ctrl-spc login` first.') {
+        super(message);
+        this.name = 'NotLoggedIn';
+    }
+}
+/**
+ * Builds a Supabase client authenticated from the stored session.
+ *
+ * The client never manages its own session persistence — we own that via
+ * config.ts — so any token rotation supabase-js performs while validating
+ * the session (`setSession` refreshing an expired access token, for
+ * instance) is written straight back to disk via `onAuthStateChange`.
+ */
+export async function getClient() {
+    const stored = readSession();
+    if (!stored || !stored.access_token || !stored.refresh_token) {
+        throw new NotLoggedIn();
+    }
+    const client = createClient(SUPABASE_URL, SUPABASE_KEY, {
+        auth: { persistSession: false, autoRefreshToken: false },
+    });
+    client.auth.onAuthStateChange((_event, session) => {
+        if (session) {
+            writeSession({
+                access_token: session.access_token,
+                refresh_token: session.refresh_token,
+            });
+        }
+    });
+    const { data, error } = await client.auth.setSession({
+        access_token: stored.access_token,
+        refresh_token: stored.refresh_token,
     });
+    if (error || !data.session) {
+        throw new NotLoggedIn(`Stored session is invalid or expired (${error?.message ?? 'no session returned'}). Run \`ctrl-spc login\` again.`);
+    }
+    return client;
 }