@ctrl-spc/cs 0.3.0 → 0.3.1

package/dist/config.js

@@ -199,7 +199,20 @@ export function writeCodebasePath(identity, localPath) {
  * On disk (not per-process) so `cs open` and the resident server agree on it.
  */
 export function companionToken() {
-    const path = filePath('companion-token');
+    return persistentToken('companion-token');
+}
+/**
+ * Stable per-install MCP tools-server token, same contract as companionToken.
+ * The loopback /mcp endpoint requires it, and it is embedded in the URL that
+ * registration writes into Claude/Codex configs — so only clients CTRL+SPC
+ * registered (or that can read this 0600 file) can reach the tools, not any
+ * process that happens to find the loopback port.
+ */
+export function mcpToken() {
+    return persistentToken('mcp-token');
+}
+function persistentToken(name) {
+    const path = filePath(name);
     if (existsSync(path)) {
         try {
             const token = readFileSync(path, 'utf8').trim();

package/dist/mcp.js

@@ -8,6 +8,7 @@ import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
 import { TOOLS_SERVER_PORT, SESSION_TTL_MS } from './env.js';
 import { agentPath } from './agents.js';
+import { mcpToken, readSession } from './config.js';
 export function attributionFromClientName(name) {
     if (!name)
         return null;
@@ -82,9 +83,63 @@ async function listTasksHandler(client, args) {
         return errorResult(`list_tasks failed: ${err.message}`);
     }
 }
+/** Columns a feedback round exposes to the agent (feature 09, Phase 5) — the
+ *  web writes `artifact_feedback` rows (cumulative review rounds, each tagged
+ *  with the presentation's primary artifact and its revision at send time); the
+ *  CLI reads them through RLS `artifact_feedback_select`
+ *  (`app.can_access_task`). Round BODIES stay web-written and immutable; the
+ *  ONE thing the CLI writes back is resolution state, via `resolve_feedback`
+ *  (hybrid resolution — the DB's status-only guard rejects any other change).
+ *  status ('open' | 'resolved' | 'reopened'), resolved_in_revision (the
+ *  revision the resolver claims addressed the round), and status_changed_at
+ *  make each round's state obvious: 'open' / 'reopened' rounds need attention,
+ *  'resolved' ones don't. */
+const FEEDBACK_BASE_COLUMNS = 'id,artifact_id,artifact_revision,body,created_at,created_by';
+const FEEDBACK_COLUMNS = `${FEEDBACK_BASE_COLUMNS},status,resolved_in_revision,status_changed_at`;
+/** True when a PostgREST/Postgres error means "column does not exist"
+ *  (SQLSTATE 42703) — the shape a database that predates migration
+ *  20260724210000 returns for the resolution columns. Detected narrowly (code
+ *  or message) so every other failure keeps surfacing as a real error. */
+function isUndefinedColumnError(error) {
+    return error.code === '42703' || /column .* does not exist/i.test(error.message);
+}
 /**
- * Read one task by id (RLS-scoped) with its tags, comments, live artifacts, and
- * decisions (D3 — so the agent can read the answers to questions it asked).
+ * Fetch a task's feedback rounds, degrading gracefully against a database that
+ * predates migration 20260724210000 (the published CLI is versioned
+ * independently of DB migrations): if selecting the resolution columns fails
+ * with an undefined-column error, retry with the pre-resolution column list
+ * and default every round to status 'open' with null resolution stamps —
+ * mirroring the web's degrade posture — instead of letting the whole get_task
+ * die. Any OTHER error still throws, so genuinely failed queries surface
+ * through get_task's normal error path.
+ */
+async function fetchFeedbackRounds(client, taskId) {
+    const roundsQuery = (columns) => client
+        .from('artifact_feedback')
+        .select(columns)
+        .eq('task_id', taskId)
+        .order('created_at', { ascending: true })
+        .order('id', { ascending: true });
+    const { data, error } = await roundsQuery(FEEDBACK_COLUMNS);
+    if (!error)
+        return data ?? [];
+    if (!isUndefinedColumnError(error))
+        throw new Error(error.message);
+    const rows = await must(roundsQuery(FEEDBACK_BASE_COLUMNS));
+    return (rows ?? []).map((row) => ({
+        ...row,
+        status: 'open',
+        resolved_in_revision: null,
+        status_changed_at: null,
+    }));
+}
+/**
+ * Read one task by id (RLS-scoped) with its tags, comments, live artifacts,
+ * decisions (D3 — so the agent can read the answers to questions it asked), and
+ * feedback rounds (feature 09, Phase 5 — the cumulative wireframe-review rounds
+ * the user sends from the web, each tagged with the presented primary artifact
+ * and its revision at send time; per-note option attribution is inline in the
+ * body).
  * Adapted from v1's `getTaskHandler` for the column shapes, with every
  * topology / checkout / coordination section dropped.
  */
@@ -98,7 +153,7 @@ async function getTaskHandler(client, args) {
             .maybeSingle());
         if (!row)
             return errorResult(`No task found for id "${args.id}".`);
-        const [comments, artifacts, decisions] = await Promise.all([
+        const [comments, artifacts, decisions, feedback] = await Promise.all([
             must(client
                 .from('comments')
                 .select('id,task_id,body,author_id,from_agent,agent_run_id,created_at,updated_at')
@@ -120,6 +175,17 @@ async function getTaskHandler(client, args) {
                 .eq('task_id', row.id)
                 .order('asked_at', { ascending: true })
                 .order('id', { ascending: true })),
+            // Feature 09 Phase 5: the item's feedback rounds — cumulative review
+            // rounds the user sent on presented artifacts (bodies web-written and
+            // immutable), oldest first, each tagged with the presentation's primary
+            // artifact and its revision at send time (the presentation's version
+            // stamp; option attribution is inline in the round's body). Each carries
+            // its resolution state (status / resolved_in_revision /
+            // status_changed_at) so the agent can tell which rounds still need
+            // attention ('open' / 'reopened') and which don't ('resolved'). Against
+            // a pre-20260724210000 database the helper degrades to the base columns
+            // with defaulted resolution state rather than failing the whole read.
+            fetchFeedbackRounds(client, row.id),
         ]);
         const { task_tags: _drop, ...task } = row;
         return textResult({
@@ -127,6 +193,7 @@ async function getTaskHandler(client, args) {
             comments: comments ?? [],
             artifacts: artifacts ?? [],
             decisions: decisions ?? [],
+            feedback: feedback ?? [],
         });
     }
     catch (err) {
@@ -153,6 +220,17 @@ async function createArtifactHandler(client, userId, currentSession, args) {
         if (args.purpose_key?.trim().startsWith('context:')) {
             return errorResult('Context is a reserved work-item artifact.');
         }
+        // The 'wireframe_option:' namespace is reserved exactly like 'context:'
+        // (feature 09, Phase 2): the web suppresses idx > 0 wireframe_option
+        // artifacts from the Artifacts list, so an agent re-using a purpose_key it
+        // saw in a present_wireframes / present_mocks result could silently hide an
+        // ordinary artifact. Mocks share the namespace deliberately (feature 10),
+        // so this ONE reservation covers both tools.
+        // update_artifact cannot set purpose_key at all (its patch is
+        // built only from title/type/format/content), so INSERT is the only door.
+        if (args.purpose_key?.trim().startsWith('wireframe_option:')) {
+            return errorResult("The purpose_key prefix 'wireframe_option:' is reserved for present_wireframes / present_mocks presentations.");
+        }
         const task = await must(client.from('tasks').select('id').eq('id', args.task_id).is('archived_at', null).maybeSingle());
         if (!task)
             return errorResult(`No task found for id "${args.task_id}".`);
@@ -514,6 +592,429 @@ async function askQuestionHandler(client, userId, session, args) {
         return errorResult(`ask_question failed: ${err.message}`);
     }
 }
+/** Option labels the review outcome reserves (feature 09, Phase 2): 'approve'
+ *  is the single-shape approval sentinel `answer_task_decision_v2`'s machinery
+ *  keys on to auto-write `artifact_approvals`, and 'request changes' is the
+ *  iterate outcome appended to EVERY review decision's options. A user-named
+ *  option matching either (case-insensitively) would collide with the outcome
+ *  derivation, so validation rejects them. */
+const RESERVED_OPTION_LABELS = ['approve', 'request changes'];
+/**
+ * Present 1..N renders to the user for fullscreen review — the composition BOTH
+ * review tools run (feature 09-present-wireframes-tool Phase 2, which REPLACED
+ * Phase 1's free_text shape; feature 10-present-mocks-tool Phase 1–2). The caller
+ * supplies a `spec`; the plumbing below is identical for wireframes and mocks
+ * on purpose, so the web's ONE review surface serves both. A COMPOSITION of
+ * existing plumbing — no new tables, no migrations, no new RPCs:
+ *   1. each render becomes a normal artifact on the SESSION'S task, inserted
+ *      exactly the way create_artifact does (AS THE USER, `from_agent` null —
+ *      the deployed guard reserves agent attribution for the coordinated path
+ *      this feature does not use — plus the same best-effort
+ *      cliv2_agent_outputs attribution, one row per artifact): type
+ *      'wireframe' for a UI diagram, 'diagram' for an architecture diagram,
+ *      'mock' for an interactive mock, format 'html'. The multi shape
+ *      (options: 2..11 of {label, html})
+ *      creates one artifact per option, in order, and maps option ↔ artifact
+ *      through purpose_key 'wireframe_option:<presentation-uuid>:<idx>' on
+ *      EVERY option artifact (idx 0 included) — the web matches decision
+ *      options[i] to the artifact with idx i. Idx 0 is the PRIMARY: it carries
+ *      the presentation title verbatim (idx > 0 titles are '<title> — <label>')
+ *      and the review decision relates to it. The single shape (html) stays
+ *      exactly Phase 1's one untagged artifact — NO purpose_key.
+ *   2. the review request becomes a single_select decision opened through the
+ *      SAME `cliv2_ask_question` RPC ask_question uses — category
+ *      'wireframe_review' is the sentinel the web keys on to render the
+ *      fullscreen review surface instead of a plain question, the context
+ *      carries the title, and `p_related_artifact` points at the primary
+ *      artifact. Options: ['approve', 'request changes'] (single) or
+ *      [...labels, 'request changes'] (multi). One uniform outcome for 1..N:
+ *      the user either APPROVES — 'approve' is the exact shape
+ *      answer_task_decision_v2 keys on to auto-write artifact_approvals;
+ *      picking an option label IS approving that option (derived in the web) —
+ *      or requests changes; their comment rides along as answer_note. Hence
+ *      'approve' / 'request changes' are RESERVED label values, and the DB's
+ *      12-option decision cap bounds the labels at 11.
+ * The review loop (Phase 5 — cumulative feedback rounds): the user sends any
+ * number of feedback rounds, any time, without waiting — each is a web-written
+ * `artifact_feedback` row tagged with the presentation's PRIMARY (idx 0)
+ * artifact and its artifact_revision at send time. That tag is the version
+ * stamp of the presentation as a whole, NOT a per-option pointer: in a
+ * multi-option presentation, which option a note concerns is named inline in
+ * the note's "(…)" option label within the round's body. The agent reads the
+ * rounds from get_task's `feedback` list (oldest first). The
+ * decision above is the APPROVAL GATE only: it stays open across rounds and
+ * decides ONLY when the user approves (selected_options[0] 'approve' or an
+ * option label; answer_note may carry a final comment). To iterate, the agent
+ * revises the presented render IN PLACE with update_artifact — the DB bumps
+ * its revision automatically, so later rounds self-identify against the new
+ * version — and keeps polling; it must NOT call the presentation tool again for
+ * iterations of the same design. Requires an open session (like ask_question —
+ * the decision lives on the session's task, so there's no task_id arg). Full
+ * version history is a later phase.
+ */
+async function presentationHandler(client, userId, session, args, spec) {
+    try {
+        if (!session) {
+            return errorResult(`${spec.tool} needs an open work session — call begin_work first.`);
+        }
+        if (!args.title || !args.title.trim())
+            return errorResult(`${spec.tool} requires a non-empty title.`);
+        const extra = spec.extraValidation?.();
+        if (extra)
+            return errorResult(extra);
+        // Exactly ONE of the two shapes: html (a single render, exactly Phase 1)
+        // or options (2..11 competing renders).
+        const hasHtml = args.html !== undefined;
+        const hasOptions = args.options !== undefined;
+        if (hasHtml && hasOptions) {
+            return errorResult(`${spec.tool} takes either html (one ${spec.unit}) or options (2..11 competing ${spec.unit}s), not both.`);
+        }
+        if (!hasHtml && !hasOptions) {
+            return errorResult(`${spec.tool} requires html (one ${spec.unit}) or options (2..11 competing ${spec.unit}s).`);
+        }
+        const multi = hasOptions;
+        let opts = [];
+        if (multi) {
+            if (!Array.isArray(args.options) || args.options.length < 2 || args.options.length > 11) {
+                return errorResult(`${spec.tool} requires 2..11 options (use html for a single ${spec.unit}; a review decision is capped at 12 options including the reserved one).`);
+            }
+            opts = args.options.map((option) => ({ label: (option.label ?? '').trim(), html: option.html ?? '' }));
+            if (opts.some((o) => !o.label)) {
+                return errorResult(`${spec.tool} requires a non-empty label for every option.`);
+            }
+            if (opts.some((o) => !o.html.trim())) {
+                return errorResult(`${spec.tool} requires non-empty html for every option (${spec.htmlSpec}).`);
+            }
+            const lowered = opts.map((o) => o.label.toLowerCase());
+            if (new Set(lowered).size !== lowered.length) {
+                return errorResult(`${spec.tool} requires distinct option labels (case-insensitive).`);
+            }
+            if (lowered.some((label) => RESERVED_OPTION_LABELS.includes(label))) {
+                return errorResult(`${spec.tool} option labels 'approve' and 'request changes' are reserved review outcomes — rename the option.`);
+            }
+        }
+        else if (!args.html || !args.html.trim()) {
+            return errorResult(`${spec.tool} requires non-empty html (${spec.htmlSpec}).`);
+        }
+        const title = args.title.trim();
+        // Sentence-initial form of the artifact noun, for the attribution warning.
+        const capitalNoun = spec.artifactNoun.charAt(0).toUpperCase() + spec.artifactNoun.slice(1);
+        // The review decision's question — the recovery message below quotes it
+        // LITERALLY, so both must come from this one string.
+        const question = `Review the ${spec.artifactNoun} and leave feedback.`;
+        // One entry per artifact to create, in presentation order (idx 0 = the
+        // primary). Multi tags EVERY entry with the option ↔ artifact mapping key;
+        // single stays untagged, exactly Phase 1.
+        const presentationId = multi ? randomUUID() : null;
+        const renders = multi
+            ? opts.map((option, idx) => ({
+                title: idx === 0 ? title : `${title} — ${option.label}`,
+                html: option.html,
+                purpose_key: `wireframe_option:${presentationId}:${idx}`,
+            }))
+            : [{ title, html: args.html, purpose_key: null }];
+        // The review decision's options: the approval outcome(s) first, 'request
+        // changes' always last (the DB caps decision options at 12, hence ≤11 labels).
+        const reviewOptions = multi ? [...opts.map((o) => o.label), 'request changes'] : ['approve', 'request changes'];
+        // The renders land on the session's task. Confirm it is live under the
+        // user's RLS first (mirrors create_artifact) so a task archived after
+        // begin_work gets a clean error instead of an opaque insert failure.
+        const task = await must(client.from('tasks').select('id').eq('id', session.taskId).is('archived_at', null).maybeSingle());
+        if (!task)
+            return errorResult(`No task found for id "${session.taskId}".`);
+        // 1. Each render as a normal artifact — the SAME insert create_artifact
+        // does, one row per render, in presentation order.
+        const created = [];
+        const attributionWarnings = [];
+        for (const render of renders) {
+            let row = null;
+            try {
+                row = await must(client
+                    .from('artifacts')
+                    .insert({
+                    task_id: session.taskId,
+                    type: spec.artifactType,
+                    format: 'html',
+                    title: render.title,
+                    ...(render.purpose_key ? { purpose_key: render.purpose_key } : {}),
+                    content: render.html,
+                    created_by: userId,
+                    from_agent: null,
+                    agent_run_id: null,
+                })
+                    .select(ARTIFACT_COLUMNS)
+                    .single());
+                if (!row)
+                    throw new Error('Artifact insert returned no row.');
+            }
+            catch (err) {
+                // Nothing created yet → fatal and generic, exactly the Phase 1 path.
+                if (created.length === 0)
+                    throw err;
+                // A later option insert failing orphans the already-created options:
+                // return them (ids included) with guidance the agent can actually act
+                // on. No tool can delete an artifact (update_artifact has no deleted_at
+                // and there is no delete tool), so "clean up" is not an instruction the
+                // agent can execute — removal is a manual web action, and the agent's
+                // job is to surface it and hold off re-presenting (a blind retry would
+                // duplicate the created options).
+                const createdIds = created.map((row) => row.id).join(', ');
+                const failure = {
+                    artifacts: created,
+                    error: `${spec.tool}: created ${created.length} of ${renders.length} option artifacts, then the insert for ` +
+                        `'${render.title}' failed: ${err.message}. No review request was opened. There is no delete ` +
+                        `tool: the created artifacts (${createdIds}) are inert until removed manually in the web. Report this ` +
+                        `failure to the user with those ids, and do NOT call ${spec.tool} again (it would duplicate the ` +
+                        'created options) until the user confirms.',
+                };
+                if (attributionWarnings.length)
+                    failure.attribution_warning = attributionWarnings.join(' ');
+                return { ...textResult(failure), isError: true };
+            }
+            created.push(row);
+            // Best-effort session attribution per artifact (mirrors create_artifact:
+            // the session's task matches by construction). The artifact already exists
+            // and is part of the real return value, so a failed attribution write must
+            // NOT fail the tool — it is surfaced in the returned text, never dropped.
+            try {
+                await must(client.from('cliv2_agent_outputs').insert({
+                    user_id: userId,
+                    session_id: session.sessionId,
+                    kind: 'artifact',
+                    product_id: row.id,
+                }));
+            }
+            catch (err) {
+                attributionWarnings.push(`${capitalNoun} artifact created, but recording session attribution failed: ${err.message}`);
+            }
+        }
+        const primary = created[0];
+        // 2. The review request as a single_select decision — the SAME RPC
+        // ask_question uses; 'wireframe_review' is the sentinel category the web
+        // keys on (feature 09). The artifacts above already exist, so from here a
+        // failure must NOT be the generic fatal error: swallowing them would orphan
+        // them in the DB (plain cards with no "feedback requested"), leave the
+        // agent with no ids to recover with, and invite a blind retry that
+        // duplicates artifacts. So this step gets its OWN try/catch (the FIRST
+        // artifact-insert failure path above stays fatal and generic), and on
+        // failure the error result STILL carries the created artifact(s) plus a
+        // message telling the agent to retry the review step — via ask_question
+        // with related_artifact_id — or clean up, not re-present.
+        let decision;
+        try {
+            const decisionId = await must(client.rpc('cliv2_ask_question', {
+                p_session: session.sessionId,
+                p_category: 'wireframe_review',
+                p_context: title,
+                p_question: question,
+                p_answer_mode: 'single_select',
+                p_options: reviewOptions,
+                p_related_artifact: primary.id,
+            }));
+            if (!decisionId)
+                throw new Error('Review request insert returned no decision id.');
+            // Best-effort attribution for the decision (mirrors ask_question exactly).
+            try {
+                await must(client.from('cliv2_agent_outputs').insert({
+                    user_id: userId,
+                    session_id: session.sessionId,
+                    kind: 'decision',
+                    product_id: decisionId,
+                }));
+            }
+            catch (err) {
+                attributionWarnings.push(`Review request created, but recording session attribution failed: ${err.message}`);
+            }
+            // Re-fetch the created decision with the SAME columns get_task returns, so
+            // the agent sees what it made and can later read the feedback back with
+            // get_task.
+            const fetched = await must(client.from('decisions').select(DECISION_COLUMNS).eq('id', decisionId).maybeSingle());
+            if (!fetched)
+                throw new Error('Created review decision could not be re-fetched.');
+            decision = fetched;
+        }
+        catch (err) {
+            // The recovery instruction must be LITERAL and complete: the web's review
+            // surface matches ONLY category === 'wireframe_review' (a sentinel that is
+            // deliberately not in any tool description, and that mocks reuse verbatim
+            // — there is no 'mock_review'), and the decision-consistency
+            // guard makes category immutable — so a plausible-but-wrong retry category
+            // would leave the review permanently stuck as a generic question. Spell out
+            // the exact ask_question call, with the real title, the full literal
+            // options array, and the primary artifact id. The multi failure payload
+            // carries ALL created artifacts (ids included).
+            const optionsLiteral = `[${reviewOptions.map((label) => `'${label}'`).join(', ')}]`;
+            const failure = {
+                ...(multi ? { artifacts: created } : { artifact: primary }),
+                error: `${spec.tool}: the ${spec.artifactNoun} artifact${multi ? 's were' : ' was'} created, but opening the review request failed: ` +
+                    `${err.message}. Do NOT call ${spec.tool} again (it would duplicate the artifact${multi ? 's' : ''}) — ` +
+                    `retry the review step with ask_question({ category: 'wireframe_review', context: '${title}', ` +
+                    `question: '${question}', answer_mode: 'single_select', ` +
+                    `options: ${optionsLiteral}, related_artifact_id: '${primary.id}' }) — the category string must be exactly ` +
+                    "'wireframe_review' or the web will not show the review UI — or clean up.",
+            };
+            if (attributionWarnings.length)
+                failure.attribution_warning = attributionWarnings.join(' ');
+            return { ...textResult(failure), isError: true };
+        }
+        const payload = {
+            ...(multi ? { artifacts: created } : { artifact: primary }),
+            decision,
+            instruction: multi
+                ? `The user has been asked to review ${created.length} competing options. They send CUMULATIVE feedback ` +
+                    "rounds — any number, any time, without waiting for you: poll get_task and read them from its `feedback` " +
+                    'list (oldest first). Every round is tagged with the presentation PRIMARY artifact (the first option) and ' +
+                    'its artifact_revision at send time — the version stamp of the presentation, NOT a per-option pointer. ' +
+                    "Which OPTION a note concerns is named inline in the note's \"(…)\" option label within the round's body. " +
+                    'This decision is the approval gate only: it stays open across rounds and decides ONLY when the user ' +
+                    'approves — once its state is decided, selected_options[0] is the approved option label and answer_note ' +
+                    'may carry a final comment. To act on feedback, revise the option artifact each note names IN PLACE with ' +
+                    'update_artifact (its revision bumps automatically), then call resolve_feedback with the ids of the ' +
+                    "rounds that revision actually addressed and the revised OPTION artifact's NEW revision number — only " +
+                    'rounds you genuinely acted on. Option revisions are their own number-space (not the primary v-tags): ' +
+                    'the review surface shows a multi round as resolved WITHOUT a version number, so name WHICH option you ' +
+                    'revised in any accompanying update, and never expect the primary revision to move when only options ' +
+                    "changed. A round the user flips back to 'reopened' is open feedback again: address it on the next pass " +
+                    `and re-resolve. Keep polling. Do NOT call ${spec.tool} ` +
+                    'again for iterations of this same design.'
+                : `The user has been asked to review the ${spec.artifactNoun}. They send CUMULATIVE feedback rounds — any number, any ` +
+                    "time, without waiting for you: poll get_task and read them from its `feedback` list (oldest first), each " +
+                    'tagged with the artifact_revision it critiques so you know which version the notes are about. This ' +
+                    'decision is the approval gate only: it stays open across rounds and decides ONLY when the user approves ' +
+                    "— once its state is decided, selected_options[0] is 'approve' and answer_note may carry a final comment. " +
+                    `To act on feedback, revise this ${spec.artifactNoun} IN PLACE with update_artifact (its revision bumps ` +
+                    'automatically, so later rounds name the new version), then call resolve_feedback with the ids of the ' +
+                    'rounds that revision actually addressed and the NEW revision number — only rounds you genuinely acted ' +
+                    "on. A round the user flips back to 'reopened' is open feedback again: address it on the next pass and " +
+                    `re-resolve. Keep polling. Do NOT call ${spec.tool} ` +
+                    'again for iterations of this same design.',
+        };
+        if (attributionWarnings.length)
+            payload.attribution_warning = attributionWarnings.join(' ');
+        return textResult(payload);
+    }
+    catch (err) {
+        return errorResult(`${spec.tool} failed: ${err.message}`);
+    }
+}
+/**
+ * present_wireframes (feature 09) — 1..N lo-fi HTML wireframes (kind 'ui') or
+ * architecture diagrams (kind 'architecture'). A thin spec over the shared
+ * presentation handler; `kind` is the only thing it adds, and it picks the
+ * artifact type. Exported (like badgeReason) so the self-check
+ * (test-tools.mjs) can exercise its branching with a stub client, without a
+ * live MCP handshake.
+ */
+export async function presentWireframesHandler(client, userId, session, args) {
+    return presentationHandler(client, userId, session, args, {
+        tool: 'present_wireframes',
+        unit: 'diagram',
+        htmlSpec: 'a self-contained lo-fi HTML/CSS diagram',
+        artifactType: args.kind === 'ui' ? 'wireframe' : 'diagram',
+        artifactNoun: 'wireframe',
+        extraValidation: () => args.kind !== 'ui' && args.kind !== 'architecture'
+            ? "present_wireframes requires kind to be 'ui' or 'architecture'."
+            : null,
+    });
+}
+/**
+ * present_mocks (feature 10-present-mocks-tool) — the mocks sibling of
+ * present_wireframes: 1..N SELF-CONTAINED INTERACTIVE mocks (HTML + CSS + JS in
+ * one document) that actually work — tabs switch, inputs type, buttons act. No
+ * `kind`: a mock IS the kind, and the artifact type is always 'mock' /
+ * format 'html'.
+ *
+ * It reuses the wireframe review plumbing WHOLESALE and on purpose — same
+ * 'wireframe_review' decision sentinel, same 'wireframe_option:' purpose_key
+ * namespace, same reserved 'approve' / 'request changes' labels, same 2..11
+ * cap, same open-session requirement, same partial-failure recovery. That is
+ * what lets the web's existing review surface (cover, Feedback drawer, rounds,
+ * resolution, approve) serve mocks with no new sentinel, no new reservation and
+ * no parallel implementation. The ONE thing the web adds for mocks is the
+ * FREEZE: while the user is in Feedback mode the injected annotate script
+ * swallows clicks/keys so they select elements to annotate instead of driving
+ * the mock (scrolling stays live) — which is why the tool description insists
+ * the mock be meaningful in its DEFAULT state.
+ *
+ * SCOPE (Phase 2): competing mocks are live. Phase 1 shipped one mock only and
+ * refused `options` here; Phase 2 lifted that guard, so a mocks presentation is
+ * now exactly a wireframes presentation with the mock nouns — one call = one
+ * presentation of 1..N options, and the user picks by approving the option on
+ * screen. The registered schema declares the shape but constrains none of it
+ * (see the comment at registerTool), so EVERY refusal below is reachable over
+ * MCP and the agent reads the written message rather than a raw zod "Too
+ * small". present_wireframes keeps its constrained schema — feature 09's
+ * shipped surface — so the two now differ there and only there.
+ */
+export async function presentMocksHandler(client, userId, session, args) {
+    return presentationHandler(client, userId, session, args, {
+        tool: 'present_mocks',
+        unit: 'mock',
+        htmlSpec: 'a self-contained interactive HTML/CSS/JS mock',
+        artifactType: 'mock',
+        artifactNoun: 'mock',
+    });
+}
+/** Loose UUID shape check (any version), so a malformed id gets a clean tool
+ *  error naming it instead of a Postgres `invalid input syntax for type uuid`
+ *  failing the whole batch. */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Mark feedback rounds resolved by a revision (feature 09, Phase 5 — hybrid
+ * resolution). After update_artifact ships a revision, the agent calls this
+ * with the ids of the rounds that revision actually addressed and the NEW
+ * revision number; each round flips to status 'resolved' with
+ * resolved_in_revision = revision. The user can flip a round back to
+ * 'reopened' in the web when the change wasn't material, and this same call
+ * re-resolves it on the next pass. This is the ONE write the CLI makes to
+ * `artifact_feedback`: a plain UPDATE as the user through RLS
+ * `artifact_feedback_update` (task access + the 'comment' grant) and the
+ * column-level grant on the four resolution columns. The DB's status-only
+ * guard keeps round bodies immutable and stamps status_changed_at/_by itself
+ * (never trusted from here), so only status + resolved_in_revision are sent.
+ *
+ * The UPDATE's `.in(...)` silently skips ids that don't exist, aren't visible
+ * under RLS, or belong to a task the user can't touch — so the result rows are
+ * compared against the request and ANY shortfall is an error that lists the
+ * missing ids (and the ones that DID update, since those flips committed).
+ * Requires an open session, like the sibling review tools. Exported (like
+ * presentWireframesHandler) so the self-check can exercise it with a stub
+ * client.
+ */
+export async function resolveFeedbackHandler(client, session, args) {
+    try {
+        if (!session) {
+            return errorResult('resolve_feedback needs an open work session — call begin_work first.');
+        }
+        if (!Array.isArray(args.feedback_ids) || args.feedback_ids.length === 0) {
+            return errorResult('resolve_feedback requires feedback_ids (at least one feedback round id).');
+        }
+        if (!Number.isInteger(args.revision) || args.revision < 1) {
+            return errorResult('resolve_feedback requires revision (a positive integer — the artifact revision that addressed the rounds).');
+        }
+        const ids = [...new Set(args.feedback_ids.map((id) => id.trim()))];
+        const malformed = ids.filter((id) => !UUID_RE.test(id));
+        if (malformed.length) {
+            return errorResult(`resolve_feedback: not valid feedback round id(s): ${malformed.join(', ')}.`);
+        }
+        const rows = (await must(client
+            .from('artifact_feedback')
+            .update({ status: 'resolved', resolved_in_revision: args.revision })
+            .in('id', ids)
+            .select('id'))) ?? [];
+        const updated = rows.map((row) => row.id);
+        if (updated.length !== ids.length) {
+            const missing = ids.filter((id) => !updated.includes(id));
+            return errorResult(`resolve_feedback: ${updated.length} of ${ids.length} round(s) updated. Not found (or not accessible): ` +
+                `${missing.join(', ')}.${updated.length ? ` Already marked resolved: ${updated.join(', ')}.` : ''} ` +
+                'Check the ids against the most recent get_task `feedback` list.');
+        }
+        return textResult({ resolved: updated, revision: args.revision });
+    }
+    catch (err) {
+        return errorResult(`resolve_feedback failed: ${err.message}`);
+    }
+}
 /**
  * Record the user's answer to an OPEN decision on the work item (feature 05 / D4 —
  * the run-free twin of v1's `record_user_input`). Unlike v1, this does NOT go through a
@@ -913,7 +1414,7 @@ async function getCredentialHandler(client, args) {
     }
 }
 // ---------------------------------------------------------------------------
-// The nineteen tools this server exposes. Exported for the self-check.
+// The twenty-two tools this server exposes. Exported for the self-check.
 // ---------------------------------------------------------------------------
 export const TOOL_NAMES = [
     'list_tasks',
@@ -927,6 +1428,9 @@ export const TOOL_NAMES = [
     'begin_work',
     'end_work',
     'ask_question',
+    'present_wireframes',
+    'present_mocks',
+    'resolve_feedback',
     'record_user_input',
     'record_context_exploration',
     'reserve_work_paths',
@@ -936,7 +1440,7 @@ export const TOOL_NAMES = [
     'list_credentials',
     'get_credential',
 ];
-/** Build a per-session McpServer with the nineteen tools. A fresh instance per
+/** Build a per-session McpServer with the twenty-two tools. A fresh instance per
  *  session is what makes `server.server.getClientVersion()` (populated during
  *  that session's `initialize`) the right source for attribution — mirroring
  *  v1's per-session `buildServer`. `connectionId` is this connection's key into
@@ -961,8 +1465,14 @@ export function buildToolsServer(client, userId, machineId, connectionId) {
         return listTasksHandler(client, args);
     });
     server.registerTool('get_task', {
-        description: 'Read a full task — its tags, comments, artifacts, and decisions (so you can read the answers to questions ' +
-            'you asked). Read-only; it has no status or presence side effects.',
+        description: 'Read a full task — its tags, comments, artifacts, decisions (so you can read the answers to questions ' +
+            'you asked), and feedback (the cumulative wireframe-review rounds the user sent, each tagged with the ' +
+            "presented primary artifact and its artifact_revision at send time — the presentation's version stamp). " +
+            "Each feedback round carries its resolution state: rounds with status 'open' or 'reopened' need your " +
+            "attention ('reopened' means the user flipped a round you resolved back to not resolved — treat it as " +
+            "open feedback on your next pass); 'resolved' rounds don't (resolved_in_revision names the revision that " +
+            'addressed them; mark rounds resolved with resolve_feedback after revising). ' +
+            'Read-only; it has no status or presence side effects.',
         inputSchema: { id: z.string().describe('Task id') },
     }, async ({ id }) => {
         touchSession(connectionId);
@@ -1178,6 +1688,132 @@ export function buildToolsServer(client, userId, machineId, connectionId) {
         touchSession(connectionId);
         return askQuestionHandler(client, userId, openSessions.get(connectionId) ?? null, args);
     });
+    server.registerTool('present_wireframes', {
+        description: 'Present lo-fi HTML wireframes (kind ui) or architecture diagrams (kind architecture) to the user for ' +
+            'fullscreen review in the web work item — either ONE diagram (html) or 2..11 competing options ' +
+            '(options: [{label, html}, …]); pass exactly one of html / options. Every html must be a self-contained ' +
+            'lo-fi HTML/CSS diagram. The user then sends CUMULATIVE feedback rounds — any number, any time, without ' +
+            "waiting for you: poll get_task and read them from its `feedback` list. Every round is tagged with the " +
+            "presentation's primary artifact and its artifact_revision at send time — the presentation's version " +
+            'stamp, not a per-option pointer; in a multi-option presentation, which option a note concerns is named ' +
+            'inline in the note\'s "(…)" option label within body, so revise the option artifact the notes name. ' +
+            'The returned review ' +
+            'decision is the approval gate only: it stays open across rounds and decides ONLY when the user approves ' +
+            "(selected_options[0] is 'approve', or the approved option's label — choosing an option is approving it; " +
+            'answer_note may carry a final comment). To act on feedback, revise the wireframe IN PLACE with ' +
+            'update_artifact (the revision bumps automatically), then call resolve_feedback with the ids of the ' +
+            'rounds that revision actually addressed and the NEW revision number — only rounds you genuinely acted ' +
+            "on. The user can flip a round back to 'reopened' when the change wasn't material; treat a reopened " +
+            'round as open feedback on the next pass (resolve_feedback re-resolves it). Keep polling — do NOT call ' +
+            'present_wireframes ' +
+            'again for iterations of the same design. Requires an open session (begin_work). If diagrams are created ' +
+            'but the review request fails, the error includes the created artifacts and exact recovery instructions ' +
+            '— follow them instead of calling this tool again.',
+        inputSchema: {
+            title: z.string().min(1).describe('Short title for the presentation (shown on the work item)'),
+            kind: z.enum(['ui', 'architecture']).describe("'ui' for wireframes, 'architecture' for code/flow diagrams"),
+            html: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('A single self-contained lo-fi HTML/CSS diagram (exactly one of html / options)'),
+            options: z
+                .array(z.object({ label: z.string().min(1), html: z.string().min(1) }))
+                .min(2)
+                .max(11)
+                .optional()
+                .describe('2..11 competing diagrams, each with a short distinct label (exactly one of html / options; ' +
+                "the labels 'approve' and 'request changes' are reserved)"),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return presentWireframesHandler(client, userId, openSessions.get(connectionId) ?? null, args);
+    });
+    server.registerTool('present_mocks', {
+        description: 'Present WORKING, INTERACTIVE HTML mocks to the user for fullscreen review in the web work item — ' +
+            'either ONE mock (html) or 2..11 competing options (options: [{label, html}, …]); pass exactly one of ' +
+            'html / options. One call = ONE presentation: the user flips between the options and picks one by ' +
+            'APPROVING the option on screen. ' +
+            'Every html must be a SELF-CONTAINED interactive mock: HTML, CSS and JS all inline in the one ' +
+            'document, with fake in-memory data, so it actually works — tabs switch, inputs type, buttons act. No ' +
+            'external assets, no network (the sandboxed iframe blocks fetch/XHR/CDN links) and no storage ' +
+            '(localStorage/cookies are unavailable) — anything that needs them will silently fail. IMPORTANT: while ' +
+            'the user is in Feedback mode the viewer FREEZES the mock — clicks and keys select elements to annotate ' +
+            'instead of driving it (only scrolling stays live) — so the mock must be readable and meaningful in its ' +
+            'DEFAULT state; never hide the substance behind an interaction the user cannot perform while annotating. ' +
+            'That applies per option: whichever option is on screen is the one that freezes. ' +
+            'The user then sends CUMULATIVE feedback rounds — any number, any time, without waiting for you: poll ' +
+            "get_task and read them from its `feedback` list. Every round is tagged with the presentation's primary " +
+            "artifact and its artifact_revision at send time — the presentation's version stamp, not a per-option " +
+            'pointer; in a multi-option presentation, which option a note concerns is named inline in the ' +
+            'note\'s "(…)" option label within body, so revise the option artifact the notes name. ' +
+            'The returned review ' +
+            'decision is the approval gate only: it stays open across rounds and decides ONLY when the user approves ' +
+            "(selected_options[0] is 'approve', or the approved option's label — choosing an option is approving it; " +
+            'answer_note may carry a final comment). To act on feedback, revise the mock IN PLACE with ' +
+            'update_artifact (the revision bumps automatically), then call resolve_feedback with the ids of the ' +
+            'rounds that revision actually addressed and the NEW revision number — only rounds you genuinely acted ' +
+            "on. The user can flip a round back to 'reopened' when the change wasn't material; treat a reopened " +
+            'round as open feedback on the next pass (resolve_feedback re-resolves it). Keep polling — do NOT call ' +
+            'present_mocks ' +
+            'again for iterations of the same design. Requires an open session (begin_work). If mocks are created ' +
+            'but the review request fails, the error includes the created artifacts and exact recovery instructions ' +
+            '— follow them instead of calling this tool again.',
+        // This schema DECLARES every field the handler reads and CONSTRAINS none
+        // of what the handler validates — the two halves of the Phase 1 defect.
+        // DECLARE, because the SDK parses args with z.object(inputSchema) and
+        // passes parseResult.data on, so a Zod object silently STRIPS anything it
+        // was not told about: a field left off is discarded and never seen by the
+        // handler (that is how `options` vanished in Phase 1). Do NOT constrain,
+        // because a zod refusal is what the AGENT receives: a `.min(1)` here, or
+        // `.min(2).max(11)` on options, pre-empts the handler's written message
+        // ("use html for a single mock; a review decision is capped at 12 options
+        // including the reserved one") with a bare "Too small: expected array to
+        // have >=2 items" — true, but it doesn't say what to do instead. So the
+        // real bounds live in `.describe()`, which is how tools/list teaches the
+        // agent the shape up front, and are ENFORCED by the shared handler, which
+        // rejects every case the removed constraints did. present_wireframes
+        // deliberately still carries those constraints: it is feature 09's
+        // shipped surface, and changing the errors its agents already get is not
+        // this feature's call to make.
+        inputSchema: {
+            title: z.string().min(1).describe('Short title for the presentation (shown on the work item)'),
+            html: z
+                .string()
+                .optional()
+                .describe('A single self-contained interactive mock: HTML + CSS + JS inline, no external assets, ' +
+                'no network, no storage (exactly one of html / options)'),
+            options: z
+                .array(z.object({ label: z.string(), html: z.string() }))
+                .optional()
+                .describe('2..11 competing mocks, each self-contained and interactive, with a short distinct label ' +
+                "(exactly one of html / options; the labels 'approve' and 'request changes' are reserved)"),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return presentMocksHandler(client, userId, openSessions.get(connectionId) ?? null, args);
+    });
+    server.registerTool('resolve_feedback', {
+        description: 'Mark feedback rounds resolved after you revised the presented artifact: pass the ids of the rounds the ' +
+            'revision actually addressed (from get_task\'s `feedback` list) and the NEW revision number ' +
+            'update_artifact returned. Only mark rounds you genuinely acted on. The user can flip a round back to ' +
+            "'reopened' when the change wasn't material — treat it as open feedback on your next pass and re-resolve " +
+            'it with this tool. Round bodies never change; only resolution state does. Requires an open session (begin_work).',
+        inputSchema: {
+            feedback_ids: z
+                .array(z.string())
+                .min(1)
+                .describe("Ids of the feedback rounds the revision addressed (from get_task's feedback list)"),
+            revision: z
+                .number()
+                .int()
+                .positive()
+                .describe('The artifact revision that addressed these rounds (from the update_artifact result)'),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return resolveFeedbackHandler(client, openSessions.get(connectionId) ?? null, args);
+    });
     server.registerTool('record_user_input', {
         description: "Record the user's answer to an open decision on your work item (e.g. an answer they gave you directly). " +
             'Updates the decision to decided; it then shows answered in the web UI.',
@@ -1406,6 +2042,7 @@ export async function startToolsServer(deps) {
     // can reach Supabase without a live MCP connection in hand.
     toolsClient = deps.client;
     const port = TOOLS_SERVER_PORT;
+    const token = mcpToken();
     const sessions = new Map();
     async function handleHttp(req, res) {
         const url = new URL(req.url ?? '/', 'http://localhost');
@@ -1418,6 +2055,22 @@ export async function startToolsServer(deps) {
             res.writeHead(404).end('Not found');
             return;
         }
+        // Client auth: only clients registered by CTRL+SPC carry the per-install
+        // token (embedded in the URL written to Claude/Codex configs). Any other
+        // local process that finds the loopback port is refused before the MCP
+        // protocol — and the credential tools — are reachable.
+        if (url.searchParams.get('token') !== token) {
+            res.writeHead(401, { 'Content-Type': 'text/plain' }).end('Unauthorized');
+            return;
+        }
+        // Logout gate: terminal `cs logout` runs in a different process and can only
+        // clear session.json — it can't reach this server's in-memory session. So
+        // every request (including ones on an already-open MCP connection) re-checks
+        // the on-disk session; once it's gone, nothing is served for the old account.
+        if (!readSession()) {
+            res.writeHead(401, { 'Content-Type': 'text/plain' }).end('Logged out');
+            return;
+        }
         try {
             const sessionIdHeader = req.headers['mcp-session-id'];
             const sessionId = typeof sessionIdHeader === 'string' ? sessionIdHeader : undefined;
@@ -1589,7 +2242,7 @@ export function registerWithClaude(port) {
     if (regStatus.claude === 'registering')
         return;
     regStatus.claude = 'registering';
-    const target = `http://127.0.0.1:${port}/mcp`;
+    const target = `http://127.0.0.1:${port}/mcp?token=${mcpToken()}`;
     opChain.claude = opChain.claude.then(() => runRegister('claude', bin, ['mcp', 'remove', '--scope', 'user', 'ctrl-spc'], ['mcp', 'add', '--scope', 'user', '--transport', 'http', 'ctrl-spc', target]));
 }
 /**
@@ -1608,7 +2261,7 @@ export function registerWithCodex(port) {
     if (regStatus.codex === 'registering')
         return;
     regStatus.codex = 'registering';
-    const target = `http://127.0.0.1:${port}/mcp`;
+    const target = `http://127.0.0.1:${port}/mcp?token=${mcpToken()}`;
     opChain.codex = opChain.codex.then(() => runRegister('codex', bin, ['mcp', 'remove', 'ctrl-spc'], ['mcp', 'add', 'ctrl-spc', '--url', target]));
 }
 /** The actual `mcp remove` for logout cleanup, run ON the agent's op chain so it

package/dist/package-version.js

@@ -0,0 +1,10 @@
+import { createRequire } from 'node:module';
+// Resolve relative to this module so the same lookup works from source, built
+// dist, and an installed npm package. npm always includes the package's root
+// package.json, even though the published files allowlist contains only dist.
+const packageMetadata = createRequire(import.meta.url)('../package.json');
+if (typeof packageMetadata.version !== 'string' || packageMetadata.version.length === 0) {
+    throw new Error('The installed @ctrl-spc/cs package does not declare a version.');
+}
+/** The version of the package that is actually running this process. */
+export const CLI_VERSION = packageMetadata.version;

package/dist/presence-heartbeat.js

@@ -0,0 +1,13 @@
+import { CLI_VERSION } from './package-version.js';
+/** Build the complete, path-free cliv2_agents row reported on every heartbeat. */
+export function buildPresenceHeartbeatPayload(input, seenAt = new Date()) {
+    return {
+        user_id: input.userId,
+        machine_id: input.machineId,
+        machine_name: input.machineName,
+        agents: input.agents,
+        platform: input.platform,
+        cli_version: CLI_VERSION,
+        last_seen_at: seenAt.toISOString(),
+    };
+}

package/dist/presence.js

@@ -4,6 +4,7 @@ import { getMachineIdentity, supersededMachineIds, clearSupersededMachineIds } f
 import { detectAgents } from './agents.js';
 import { startToolsServer, stopToolsServer, toolsServerStatus, registerWithClaude, registerWithCodex, unregisterFromClaude, unregisterFromCodex, agentRegStatus, heartbeatOpenSessions, setToolsClient, } from './mcp.js';
 import { HEARTBEAT_INTERVAL_MS, COMMAND_POLL_INTERVAL_MS } from './env.js';
+import { buildPresenceHeartbeatPayload } from './presence-heartbeat.js';
 let presence = null;
 /** In-flight guard: startPresence yields to the event loop (network setSession)
  *  before `presence` is assigned, so a plain `if (presence)` check lets two
@@ -17,14 +18,13 @@ async function heartbeat(p) {
     try {
         const { error } = await p.client
             .from('cliv2_agents')
-            .upsert({
-            user_id: p.userId,
-            machine_id: p.identity.id,
-            machine_name: p.identity.name,
+            .upsert(buildPresenceHeartbeatPayload({
+            userId: p.userId,
+            machineId: p.identity.id,
+            machineName: p.identity.name,
             agents: p.agents,
             platform: p.platform,
-            last_seen_at: new Date().toISOString(),
-        }, { onConflict: 'user_id,machine_id' });
+        }), { onConflict: 'user_id,machine_id' });
         if (error)
             throw error;
     }

package/dist/supabase.js

@@ -68,7 +68,10 @@ export async function getClient() {
         global: { fetch: retryingFetch },
     });
     client.auth.onAuthStateChange((_event, session) => {
-        if (session) {
+        // Update-only: a token refresh must never recreate session.json after
+        // `cs logout` deleted it, or the logged-out machine would re-authorize
+        // itself up to an hour later.
+        if (session && readSession()) {
             writeSession({ access_token: session.access_token, refresh_token: session.refresh_token });
         }
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctrl-spc/cs",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "CTRL+SPC — minimal, reliable per-machine agent presence. Sign-in, auto-start, agent detection, heartbeat presence, and ping acknowledgement.",
   "engines": {
     "node": ">=22"
@@ -17,7 +17,8 @@
   },
   "scripts": {
     "build": "tsc",
-    "start": "npm run build && node dist/index.js"
+    "start": "npm run build && node dist/index.js",
+    "test": "npm run build && node --test test/*.test.mjs"
   },
   "license": "UNLICENSED",
   "dependencies": {
@@ -25,6 +26,9 @@
     "@supabase/supabase-js": "^2.110.1",
     "zod": "^4.4.3"
   },
+  "overrides": {
+    "@hono/node-server": "^2.0.5"
+  },
   "devDependencies": {
     "@types/node": "^26.1.1",
     "typescript": "^5.9.3"