@ctrl-spc/cli 1.3.4 → 1.3.6

package/dist/commands/init.js

@@ -9,6 +9,7 @@ import { ask, select } from '../prompt.js';
 import { buildTopologyTargets, componentTargetId, discoverRepositoryTopology, planExplicitGrouping, readGroupingManifest, repositoryTargetId, } from '../topology.js';
 import { upsertProjectLink } from './link.js';
 import { registerMachineWorkspace } from './run.js';
+import { installWakeAgent } from '../wake.js';
 function setGrouping(flags, grouping) {
     if (flags.grouping) {
         throw new Error(`Choose exactly one grouping option: --combine, --split, or --manifest <file>.`);
@@ -448,6 +449,9 @@ export async function init(argv = [], deps = {}) {
         return;
     }
     const client = await getClient();
+    if (installWakeAgent()) {
+        console.log('Remote start enabled — this computer checks in every 60s so you can start it from the web. Disable: ctrl-spc wake off');
+    }
     const { data: userData, error: userError } = await client.auth.getUser();
     if (userError || !userData.user) {
         console.error(`Could not resolve the signed-in user: ${userError?.message ?? 'no user returned'}`);

package/dist/commands/login.js

@@ -4,6 +4,7 @@ import { randomBytes, timingSafeEqual } from 'node:crypto';
 import { SUPABASE_URL, SUPABASE_KEY } from '../env.js';
 import { writeSession } from '../config.js';
 import { getClient } from '../supabase.js';
+import { installWakeAgent } from '../wake.js';
 const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
 /** POST /callback bodies larger than this are rejected before JSON parsing. */
 const MAX_CALLBACK_BODY_BYTES = 64 * 1024;
@@ -16,6 +17,9 @@ export async function login() {
     const outcome = await runLoginServer();
     if (outcome.ok) {
         console.log(`Signed in as ${outcome.email}`);
+        if (installWakeAgent()) {
+            console.log('Remote start enabled — this computer checks in every 60s so you can start it from the web. Disable: ctrl-spc wake off');
+        }
         process.exitCode = 0;
     }
     else {

package/dist/commands/logout.js

@@ -1,12 +1,41 @@
-import { clearSession } from '../config.js';
+import { clearSession, getMachineIdentity } from '../config.js';
+import { getClient } from '../supabase.js';
+import { removeWakeAgent } from '../wake.js';
+async function defaultNullHeartbeats() {
+    const client = await getClient();
+    const { error } = await client
+        .from('machines')
+        .update({ waker_seen_at: null, broker_seen_at: null })
+        .eq('id', getMachineIdentity().id);
+    if (error)
+        throw error;
+}
 /**
  * `ctrl-spc logout`: deletes the stored session. Local-only — the refresh
  * token is discarded, not revoked server-side (Supabase revokes it on next
  * rotation attempt; fine for v1's single-session CLI).
  */
-export function logout() {
-    if (clearSession()) {
-        console.log('Logged out — stored session removed.');
+export async function logout(deps = {}) {
+    try {
+        await (deps.nullHeartbeats ?? defaultNullHeartbeats)();
+    }
+    catch {
+        // Offline or already signed out. The freshness window removes stale UI.
+    }
+    let wakeRemovalFailed = false;
+    try {
+        ;
+        (deps.removeWake ?? removeWakeAgent)();
+    }
+    catch {
+        // Clearing the authenticated session is the security boundary. A stale
+        // plist without a session can only wake, fail authentication, and exit.
+        wakeRemovalFailed = true;
+    }
+    if ((deps.clear ?? clearSession)()) {
+        console.log(wakeRemovalFailed
+            ? 'Logged out — stored session removed. The background start check could not be removed, but it no longer has access to your account.'
+            : 'Logged out — stored session removed and remote start disabled.');
     }
     else {
         console.log('No stored session — already logged out.');

package/dist/commands/run.js

@@ -13,6 +13,7 @@ import { startMcpServer } from '../mcp.js';
 import { getMachineIdentity } from '../config.js';
 import { discoverRepositoryTopology } from '../topology.js';
 import { createAgentDispatchController } from '../dispatch.js';
+import { installWakeAgent, stampMachineHeartbeat } from '../wake.js';
 function mcpUrl() {
     return `http://localhost:${MCP_PORT}/mcp`;
 }
@@ -758,12 +759,13 @@ export function createProjectPresenceReconciler(client, userId, profileName, mac
  * tool call can flip presence back to "working" mid-shutdown) and only then
  * untracks presence, before exiting.
  */
-function installShutdownHandler(presence, mcpServer, dispatch) {
+function installShutdownHandler(presence, mcpServer, dispatch, onShutdown) {
     let shuttingDown = false;
     const shutdown = () => {
         if (shuttingDown)
             return;
         shuttingDown = true;
+        onShutdown?.();
         dispatch?.stop();
         console.log('\nShutting down — closing MCP server, untracking presence...');
         mcpServer
@@ -785,6 +787,8 @@ export async function run() {
     if (retireLegacyDaemon()) {
         console.log('Removed obsolete CTRL+SPC background launcher.');
     }
+    if (process.argv[2] !== '__broker')
+        installWakeAgent();
     const cwd = process.cwd();
     const client = await getClient();
     const { data: userData, error: userError } = await client.auth.getUser();
@@ -865,13 +869,21 @@ export async function run() {
         await presence.stop().catch(() => { });
         throw formatMcpStartupError(err, MCP_PORT);
     }
+    // A broker heartbeat means the local server is genuinely accepting work.
+    // Stamp only after startMcpServer succeeds; otherwise a port/startup failure
+    // would make the web app show this computer as online for three minutes.
+    await stampMachineHeartbeat(client, machine.id, true).catch(() => { });
+    const heartbeatTimer = setInterval(() => {
+        void stampMachineHeartbeat(client, machine.id, true).catch(() => { });
+    }, 60_000);
+    heartbeatTimer.unref();
     console.log(`MCP: ${url} (tools: list_tasks, get_task, begin_work, heartbeat_work, reserve_work_paths, ` +
         'release_work_paths, transfer_coordination, acknowledge_unavailable_checkout, record_context_exploration, ' +
         'set_task_role_slugs, ' +
         'ask_question, record_user_input, submit_workflow_stage, decide_workflow_review, ' +
-        'end_work, create_task, update_task, create_artifact, add_comment)');
+        'end_work, create_task, update_task, create_artifact, update_artifact, add_comment)');
     console.log(`Projects: ${projects.length > 0 ? projects.map((project) => project.name).join(', ') : 'none initialized on this machine'}`);
     console.log('Presence: available');
     const dispatch = createAgentDispatchController(client, machine.id, registeredAgents);
-    installShutdownHandler(presence, mcpServer, dispatch);
+    installShutdownHandler(presence, mcpServer, dispatch, () => clearInterval(heartbeatTimer));
 }

package/dist/index.js

@@ -6,6 +6,7 @@ import { link } from './commands/link.js';
 import { fetchRepository } from './commands/fetch.js';
 import { run } from './commands/run.js';
 import { openCompanion, serveCompanion } from './companion.js';
+import { installWakeAgent, removeWakeAgent, wakeCheck } from './wake.js';
 export const HELP_TEXT = `ctrl-spc — CTRL+SPC CLI
 
 Usage:
@@ -18,6 +19,8 @@ Usage:
   ctrl-spc fetch    Clone and link one unavailable project repository
                     [repository-id] [--project <project-id>] [--destination <path>] [--yes]
   ctrl-spc open     Open the local connection manager
+  ctrl-spc wake     Enable/disable starting this computer's agents from the web
+                    on|off
   ctrl-spc          Run the local agent process (presence + MCP server)
   ctrl-spc --help   Show this help text
 `;
@@ -28,7 +31,7 @@ export async function main(argv = process.argv.slice(2)) {
             await login();
             return;
         case 'logout':
-            logout();
+            await logout();
             return;
         case 'init':
             await init(argv.slice(1));
@@ -42,6 +45,25 @@ export async function main(argv = process.argv.slice(2)) {
         case 'open':
             await openCompanion();
             return;
+        case 'wake':
+            if (argv[1] === 'off') {
+                console.log(removeWakeAgent()
+                    ? 'Remote start disabled on this computer.'
+                    : 'Remote start was not enabled.');
+            }
+            else if (argv[1] === 'on') {
+                console.log(installWakeAgent()
+                    ? 'Remote start enabled — this computer checks in every 60s. Disable: ctrl-spc wake off'
+                    : 'Remote start requires macOS.');
+            }
+            else {
+                console.error('Usage: ctrl-spc wake on|off');
+                process.exitCode = 1;
+            }
+            return;
+        case '__wake-check':
+            await wakeCheck();
+            return;
         case '__broker':
             await run();
             return;

package/dist/mcp.js

@@ -437,7 +437,15 @@ export async function beginAgentRunHandler(deps, session, args) {
                 // field as already provided only for backwards-compatible embedded
                 // clients/test doubles that predate this contract.
                 const persistedInstruction = typeof task.description === 'string' ? task.description.trim() : null;
-                session.run.noWorkflowIntent = persistedInstruction === '' && !args.prompt_instruction?.trim()
+                const acceptedIntentDecisions = (await must(deps.client
+                    .from('decisions')
+                    .select('id')
+                    .eq('task_id', args.task_id)
+                    .eq('category', 'intent')
+                    .eq('state', 'decided')
+                    .order('decided_at', { ascending: false }))) ?? [];
+                session.run.noWorkflowIntent = persistedInstruction === '' &&
+                    !args.prompt_instruction?.trim() && acceptedIntentDecisions.length === 0
                     ? 'missing'
                     : 'provided';
             }
@@ -683,7 +691,7 @@ function explorationArtifactContent(args, orderedCoverage) {
  * mutation. The receipt is deliberately session-local while its evidence is a
  * durable analysis artifact tied to the exact task, run, and topology revision.
  */
-export async function recordContextExplorationHandler(deps, attribution, session, args) {
+export async function recordContextExplorationHandler(deps, _attribution, session, args) {
     const active = joinedRunOrError(session, 'record_context_exploration');
     if ('content' in active)
         return active;
@@ -742,20 +750,23 @@ export async function recordContextExplorationHandler(deps, attribution, session
                 return errorResult('Exploration coverage acknowledgement_id is required only for unavailable_acknowledged repositories.');
             }
         }
-        const artifactResult = await createArtifactHandler(bindProject(deps, active.projectId), attribution, {
-            task_id: active.taskId,
-            type: 'analysis',
-            format: 'md',
-            content: explorationArtifactContent(args, orderedCoverage),
-            coverage: orderedCoverage,
-        }, active);
-        if (artifactResult.isError)
-            return artifactResult;
-        const first = artifactResult.content[0];
-        if (!first || first.type !== 'text')
-            throw new Error('analysis artifact returned no text result');
-        const payload = JSON.parse(first.text);
-        const artifactId = typeof payload.artifact?.id === 'string' ? payload.artifact.id : null;
+        const content = explorationArtifactContent(args, orderedCoverage);
+        const existingContext = await must(deps.client
+            .from('artifacts')
+            .select('revision')
+            .eq('task_id', active.taskId)
+            .eq('system_kind', 'context')
+            .is('deleted_at', null)
+            .maybeSingle());
+        const artifact = await must(deps.client.rpc('record_context_exploration_artifact', {
+            p_run: active.runId,
+            p_claim_fencing_token: active.fencingToken,
+            p_topology_revision: active.topologyRevision,
+            p_expected_revision: existingContext ? Number(existingContext.revision) : null,
+            p_content: content,
+            p_coverage: orderedCoverage,
+        }));
+        const artifactId = typeof artifact?.id === 'string' ? artifact.id : null;
         if (!artifactId)
             throw new Error('analysis artifact returned no id');
         session.exploration = {
@@ -778,6 +789,10 @@ export async function recordContextExplorationHandler(deps, attribution, session
         });
     }
     catch (err) {
+        if (err instanceof Error && err.message === 'context_conflict') {
+            return errorResult('record_context_exploration found newer work-item context. Reload the work item, ' +
+                'reconcile the latest context with these reports, and retry so no findings are lost.');
+        }
         return coordinationError('record_context_exploration', err);
     }
 }
@@ -793,92 +808,82 @@ function isPersistedAgentQuestion(row, taskId, agentRunId) {
         QUESTION_CATEGORIES.includes(match[1]) &&
         isRealQuestion(match[2]));
 }
-export async function askQuestionHandler(deps, attribution, args, agentRun) {
+export async function askQuestionHandler(deps, _attribution, args, agentRun) {
     if (args.task_id !== agentRun.taskId) {
         return errorResult(`ask_question must stay on this agent run's task (${agentRun.taskId}).`);
     }
     if (!QUESTION_CATEGORIES.includes(args.category))
         return errorResult('ask_question requires a supported category.');
+    if (!args.context?.trim())
+        return errorResult('ask_question requires concise context for the decision.');
     if (!isRealQuestion(args.question)) {
         return errorResult('ask_question requires real question text containing a question mark.');
     }
     const question = args.question.trim();
-    const result = await addCommentHandler(bindProject(deps, agentRun.projectId), attribution, { task_id: agentRun.taskId, body: `[question:${args.category}] ${question}` }, agentRun.runId);
-    if (result.isError)
-        return result;
-    const first = result.content[0];
-    if (!first || first.type !== 'text')
-        return errorResult('ask_question returned no persisted comment.');
-    const payload = JSON.parse(first.text);
-    const commentId = typeof payload.comment?.id === 'string' ? payload.comment.id : null;
-    let workflowQuestionId = null;
-    if (agentRun.workflow?.enabled) {
-        if (!commentId)
-            return errorResult('ask_question returned no persisted comment id for the workflow question.');
-        workflowQuestionId = await must(deps.client.rpc('open_workflow_question', {
+    let opened;
+    try {
+        opened = await must(deps.client.rpc('ask_agent_question', {
             p_run: agentRun.runId,
-            p_comment: commentId,
             p_category: args.category,
+            p_context: args.context.trim(),
             p_question: question,
+            p_related_artifact: args.related_artifact_id ?? null,
         }));
+    }
+    catch (err) {
+        return coordinationError('ask_question', err);
+    }
+    if (!opened)
+        return errorResult('ask_question returned no persisted question.');
+    const comment = opened?.comment && typeof opened.comment === 'object'
+        ? opened.comment
+        : null;
+    const commentId = typeof comment?.id === 'string' ? comment.id : null;
+    if (!commentId)
+        return errorResult('ask_question returned no persisted comment id for the decision.');
+    const decisionId = typeof opened?.decision_id === 'string' ? opened.decision_id : null;
+    const workflowQuestionId = typeof opened?.workflow_question_id === 'string' ? opened.workflow_question_id : null;
+    if (!decisionId)
+        return errorResult('ask_question returned no persisted decision id.');
+    if (agentRun.workflow?.enabled) {
         agentRun.workflow = await loadWorkflowContext(deps.client, agentRun.taskId);
     }
     return textResult({
         question: {
             category: args.category,
             text: question,
+            context: args.context.trim(),
             comment_id: commentId,
+            decision_id: decisionId,
             workflow_question_id: workflowQuestionId,
+            related_artifact_id: args.related_artifact_id ?? null,
         },
-        comment: payload.comment ?? null,
+        comment,
         ...(agentRun.workflow?.enabled ? { workflow: agentRun.workflow } : {}),
     });
 }
-export async function recordUserInputHandler(deps, attribution, session, args) {
+export async function recordUserInputHandler(deps, _attribution, session, args) {
     const active = joinedRunOrError(session, 'record_user_input');
     if ('content' in active)
         return active;
-    if (!active.workflow?.enabled)
-        return errorResult('record_user_input requires a workflow task.');
     const capabilityError = workflowCapabilityError(active, 'record_user_input', 'record_user_input');
     if (capabilityError)
         return capabilityError;
-    if (!Array.isArray(args.question_ids) || args.question_ids.length === 0) {
-        return errorResult('record_user_input requires at least one workflow question id.');
+    const decisionIds = args.decision_ids ?? args.question_ids;
+    if (!Array.isArray(decisionIds) || decisionIds.length === 0) {
+        return errorResult('record_user_input requires at least one decision id returned by ask_question.');
     }
     if (!args.answer?.trim())
         return errorResult('record_user_input requires the user\'s exact answer.');
     try {
-        const openQuestions = active.workflow.open_questions ?? [];
-        const questionText = args.question_ids.map((id) => {
-            const question = openQuestions.find((candidate) => candidate.id === id);
-            return `- ${typeof question?.question === 'string' ? question.question : id}`;
-        }).join('\n');
-        const artifactResult = await createArtifactHandler(bindProject(deps, active.projectId), attribution, {
-            task_id: active.taskId,
-            type: 'analysis',
-            format: 'md',
-            content: `# User input\n\n## Questions\n\n${questionText}\n\n## User answer\n\n${args.answer.trim()}`,
-            coverage: args.coverage,
-        }, active);
-        if (artifactResult.isError)
-            return artifactResult;
-        const first = artifactResult.content[0];
-        if (!first || first.type !== 'text')
-            throw new Error('answer artifact returned no text result');
-        const payload = JSON.parse(first.text);
-        const artifactId = typeof payload.artifact?.id === 'string' ? payload.artifact.id : null;
-        if (!artifactId)
-            throw new Error('answer artifact returned no id');
-        active.workflow = normalizeWorkflowContext(await must(deps.client.rpc('record_workflow_answer', {
+        active.workflow = normalizeWorkflowContext(await must(deps.client.rpc('record_task_decisions', {
             p_run: active.runId,
-            p_question_ids: args.question_ids,
-            p_artifact: artifactId,
+            p_decision_ids: decisionIds,
+            p_answer: args.answer,
         })));
         return textResult({
             recorded: true,
-            artifact_id: artifactId,
-            question_ids: args.question_ids,
+            decision_ids: decisionIds,
             workflow: active.workflow,
         });
     }
@@ -934,27 +939,6 @@ export async function decideWorkflowReviewHandler(deps, session, args) {
         return errorResult('decide_workflow_review requires the user\'s exact approval or change-request message as evidence.');
     }
     try {
-        const scopes = await activeRepositoryScopes(deps.client, active.projectId);
-        const evidenceResult = await createArtifactHandler(bindProject(deps, active.projectId), attributionFromClientName(session.clientName), {
-            task_id: active.taskId,
-            type: 'analysis',
-            format: 'md',
-            content: `# Workflow review decision\n\n${args.user_message.trim()}`,
-            coverage: scopes.map(scope => ({
-                repository_scope_id: scope.repository_scope_id,
-                disposition: 'context_only',
-                reason: 'Conversation review evidence applies to this workflow task.',
-            })),
-        }, active);
-        if (evidenceResult.isError)
-            return evidenceResult;
-        const evidenceBlock = evidenceResult.content[0];
-        if (!evidenceBlock || evidenceBlock.type !== 'text')
-            throw new Error('review evidence artifact returned no text result');
-        const evidencePayload = JSON.parse(evidenceBlock.text);
-        const evidenceArtifactId = typeof evidencePayload.artifact?.id === 'string' ? evidencePayload.artifact.id : null;
-        if (!evidenceArtifactId)
-            throw new Error('review evidence artifact returned no id');
         const context = normalizeWorkflowContext(await must(deps.client.rpc('decide_workflow_review', {
             p_task: args.task_id,
             p_stage_run: args.stage_run_id,
@@ -963,17 +947,15 @@ export async function decideWorkflowReviewHandler(deps, session, args) {
             p_source: 'agent_conversation',
             p_evidence: args.user_message.trim(),
             p_agent_run: active.runId,
-            p_evidence_artifact: evidenceArtifactId,
+            p_evidence_artifact: null,
             p_dispatch_agent: false,
         })));
         if (session.run?.state === 'joined' && session.run.taskId === args.task_id) {
             session.run.workflow = context;
         }
-        session.reviewEvidenceArtifactId = evidenceArtifactId;
         return textResult({
             recorded: true,
             decision: args.decision,
-            evidence_artifact_id: evidenceArtifactId,
             workflow: context,
             instruction: context.state === 'completed'
                 ? 'The user approved completion. The workflow and work item are Done.'
@@ -991,11 +973,9 @@ export async function endAgentRunHandler(deps, session, args = {}, options = {})
     try {
         if (options.requirePersistenceReceipt) {
             const exploration = session.exploration;
-            const reviewEvidenceArtifactId = session.reviewEvidenceArtifactId ?? null;
             const receipt = args.persistence_receipt;
-            if ((!exploration && !reviewEvidenceArtifactId) || !receipt) {
-                return errorResult('end_work requires a persistence_receipt and this session\'s persisted context or review evidence artifact.');
-            }
+            if (!receipt)
+                return errorResult('end_work requires a persistence_receipt for this session.');
             const outcome = receipt.outcome ?? 'completed';
             if (exploration?.status === 'blocked' && !['blocked', 'aborted'].includes(outcome)) {
                 return errorResult('A subagents_unavailable session may end only with outcome blocked or aborted.');
@@ -1018,16 +998,15 @@ export async function endAgentRunHandler(deps, session, args = {}, options = {})
             if (!Number.isInteger(receipt.final_task_revision) || receipt.final_task_revision < 1) {
                 return errorResult('end_work persistence_receipt requires a positive final_task_revision.');
             }
-            if (!Array.isArray(receipt.artifact_ids) || receipt.artifact_ids.length === 0) {
-                return errorResult('end_work persistence_receipt requires persisted artifact ids.');
-            }
+            if (!Array.isArray(receipt.artifact_ids))
+                return errorResult('end_work persistence_receipt requires artifact_ids.');
             const artifactIds = [...new Set(receipt.artifact_ids)];
             if (artifactIds.length !== receipt.artifact_ids.length) {
                 return errorResult('end_work persistence_receipt artifact_ids must be unique.');
             }
-            const requiredEvidenceArtifactId = exploration?.artifactId ?? reviewEvidenceArtifactId;
-            if (!artifactIds.includes(requiredEvidenceArtifactId)) {
-                return errorResult('end_work persistence_receipt must include this session\'s required evidence artifact id.');
+            const requiredContextArtifactId = exploration?.artifactId ?? null;
+            if (requiredContextArtifactId && !artifactIds.includes(requiredContextArtifactId)) {
+                return errorResult('end_work persistence_receipt must include this session\'s context artifact id.');
             }
             const task = await must(deps.client
                 .from('tasks')
@@ -1040,25 +1019,29 @@ export async function endAgentRunHandler(deps, session, args = {}, options = {})
             }
             const artifactRows = (await must(deps.client
                 .from('artifacts')
-                .select('id,task_id,agent_run_id,deleted_at')
+                .select('id,task_id,agent_run_id,updated_by_agent_run_id,deleted_at')
                 .eq('task_id', active.taskId)
-                .eq('agent_run_id', active.runId)
                 .is('deleted_at', null)
                 .order('created_at', { ascending: true })
                 .order('id', { ascending: true }))) ?? [];
             const artifactsById = new Map(artifactRows.map((artifact) => [artifact.id, artifact]));
-            const persistedArtifactIds = artifactRows.map((artifact) => artifact.id);
+            const persistedArtifactIds = artifactRows
+                .filter((artifact) => (artifact.agent_run_id === active.runId || artifact.updated_by_agent_run_id === active.runId))
+                .map((artifact) => artifact.id);
+            if (requiredContextArtifactId && !persistedArtifactIds.includes(requiredContextArtifactId)) {
+                persistedArtifactIds.push(requiredContextArtifactId);
+            }
             const missingArtifactIds = persistedArtifactIds.filter((id) => !artifactIds.includes(id));
-            const foreignArtifactIds = artifactIds.filter((id) => !artifactsById.has(id));
+            const persistedArtifactIdSet = new Set(persistedArtifactIds);
+            const foreignArtifactIds = artifactIds.filter((id) => !persistedArtifactIdSet.has(id));
             if (missingArtifactIds.length > 0 || foreignArtifactIds.length > 0) {
                 return errorResult('end_work persistence_receipt artifact_ids must exactly match every non-deleted artifact persisted by ' +
                     `this task run. Missing: ${missingArtifactIds.join(', ') || 'none'}. ` +
                     `Foreign or deleted: ${foreignArtifactIds.join(', ') || 'none'}.`);
             }
-            const evidenceArtifact = artifactsById.get(requiredEvidenceArtifactId);
-            if (!evidenceArtifact || evidenceArtifact.task_id !== active.taskId ||
-                evidenceArtifact.agent_run_id !== active.runId) {
-                return errorResult('end_work could not verify this session\'s required evidence artifact.');
+            const contextArtifact = requiredContextArtifactId ? artifactsById.get(requiredContextArtifactId) : null;
+            if (requiredContextArtifactId && (!contextArtifact || contextArtifact.task_id !== active.taskId)) {
+                return errorResult('end_work could not verify this session\'s context artifact.');
             }
         }
         const ended = await must(deps.client.rpc('end_agent_run', {
@@ -1067,7 +1050,6 @@ export async function endAgentRunHandler(deps, session, args = {}, options = {})
         }));
         session.run = null;
         session.exploration = null;
-        session.reviewEvidenceArtifactId = null;
         return textResult({
             ended: Boolean(ended),
             agent_run_id: active.runId,
@@ -1172,7 +1154,7 @@ export async function getTaskHandler(deps, _attribution, args, machineId) {
         }
         const task = parseTaskRow(row);
         const topologyMachineId = machineId ?? deps.machineId;
-        const [rawComments, rawArtifacts, rawVersions, rawAgentRuns, rawTaskClaims, collaborationDocument, topology, workflow] = await Promise.all([
+        const [rawComments, rawArtifacts, rawDecisions, rawVersions, rawAgentRuns, rawTaskClaims, collaborationDocument, topology, workflow] = await Promise.all([
             must(client
                 .from('comments')
                 .select(COMMENT_SELECT)
@@ -1186,6 +1168,12 @@ export async function getTaskHandler(deps, _attribution, args, machineId) {
                 .is('deleted_at', null)
                 .order('created_at', { ascending: true })
                 .order('id', { ascending: true })),
+            must(client
+                .from('decisions')
+                .select('*')
+                .eq('task_id', row.id)
+                .order('asked_at', { ascending: true })
+                .order('id', { ascending: true })),
             must(client
                 .from('task_versions')
                 .select(TASK_VERSION_SELECT)
@@ -1222,12 +1210,19 @@ export async function getTaskHandler(deps, _attribution, args, machineId) {
         ]);
         const comments = sortRecords((rawComments ?? []).map(normalizeComment), 'created_at', 'id');
         const normalizedArtifacts = sortRecords((rawArtifacts ?? []).map(normalizeArtifact), 'created_at', 'id');
+        const hiddenArtifactKinds = new Set([
+            'superseded_context',
+            'legacy_decision_evidence',
+            'legacy_review_evidence',
+        ]);
+        const visibleArtifacts = normalizedArtifacts.filter((artifact) => (artifact.id === highlightArtifactId || !hiddenArtifactKinds.has(String(artifact.system_kind ?? ''))));
         const artifacts = highlightArtifactId
             ? [
-                ...normalizedArtifacts.filter((artifact) => artifact.id === highlightArtifactId),
-                ...normalizedArtifacts.filter((artifact) => artifact.id !== highlightArtifactId),
+                ...visibleArtifacts.filter((artifact) => artifact.id === highlightArtifactId),
+                ...visibleArtifacts.filter((artifact) => artifact.id !== highlightArtifactId),
             ]
-            : normalizedArtifacts;
+            : visibleArtifacts;
+        const decisions = sortRecords(rawDecisions ?? [], 'asked_at', 'id');
         const taskVersions = sortRecords(rawVersions ?? [], 'seq', 'id');
         const now = Date.now();
         const leaseIsLive = (value) => typeof value === 'string' && Number.isFinite(new Date(value).getTime()) && new Date(value).getTime() > now;
@@ -1270,6 +1265,7 @@ export async function getTaskHandler(deps, _attribution, args, machineId) {
             dependent_edges: task.dependent_edges,
             comments,
             artifacts,
+            decisions,
             task_versions: taskVersions,
             active_agent_runs: activeAgentRuns,
             active_task_claims: activeTaskClaims,
@@ -1408,6 +1404,9 @@ export async function createArtifactHandler(deps, attribution, args, agentRun) {
             return errorResult('create_artifact requires task_id.');
         if (!args.content)
             return errorResult('create_artifact requires content.');
+        if (args.purpose_key?.trim().startsWith('context:')) {
+            return errorResult('Context is a reserved work-item artifact. Use record_context_exploration instead.');
+        }
         if (agentRun) {
             if (agentRun.state !== 'joined') {
                 return errorResult('create_artifact is blocked while repositories are unavailable. Fetch or acknowledge them, then call begin_work again.');
@@ -1415,6 +1414,11 @@ export async function createArtifactHandler(deps, attribution, args, agentRun) {
             if (args.task_id !== agentRun.taskId) {
                 return errorResult(`create_artifact task_id must match this agent run's task (${agentRun.taskId}).`);
             }
+            if (!args.title?.trim())
+                return errorResult('create_artifact requires a title for agent artifacts.');
+            if (!args.purpose_key?.trim()) {
+                return errorResult('create_artifact requires a stable purpose_key for agent artifacts.');
+            }
             if (!Array.isArray(args.coverage) || args.coverage.length === 0) {
                 return errorResult('create_artifact requires repository coverage for every active project scope.');
             }
@@ -1433,6 +1437,8 @@ export async function createArtifactHandler(deps, attribution, args, agentRun) {
                 p_topology_revision: agentRun.topologyRevision,
                 p_type: args.type,
                 p_format: args.format ?? 'md',
+                p_title: args.title.trim(),
+                p_purpose_key: args.purpose_key.trim(),
                 p_content: args.content,
                 p_storage_path: null,
                 p_coverage: args.coverage.map((coverage) => ({
@@ -1459,12 +1465,14 @@ export async function createArtifactHandler(deps, attribution, args, agentRun) {
             task_id: args.task_id,
             type: args.type,
             format: args.format ?? 'md',
+            ...(args.title?.trim() ? { title: args.title.trim() } : {}),
+            ...(args.purpose_key?.trim() ? { purpose_key: args.purpose_key.trim() } : {}),
             content: args.content,
             created_by: deps.userId,
             from_agent: null,
             agent_run_id: null,
         })
-            .select('id,task_id,type,format,content,storage_path,created_by,from_agent,created_at')
+            .select('id,task_id,type,format,title,purpose_key,system_kind,content,storage_path,created_by,from_agent,created_at')
             .single());
         if (!row)
             throw new Error('Artifact insert returned no row.');
@@ -1476,6 +1484,63 @@ export async function createArtifactHandler(deps, attribution, args, agentRun) {
         return errorResult(`create_artifact failed: ${err.message}`);
     }
 }
+export async function updateArtifactHandler(deps, args, agentRun) {
+    try {
+        if (agentRun.state !== 'joined') {
+            return errorResult('update_artifact is blocked while repositories are unavailable. Fetch or acknowledge them, then call begin_work again.');
+        }
+        if (!args.id)
+            return errorResult('update_artifact requires an artifact id.');
+        if (!Number.isInteger(args.expected_revision) || args.expected_revision < 1) {
+            return errorResult('update_artifact requires the current positive artifact revision from get_task.');
+        }
+        if (!args.title?.trim())
+            return errorResult('update_artifact requires a title.');
+        if (!args.purpose_key?.trim())
+            return errorResult('update_artifact requires a stable purpose_key.');
+        if (args.purpose_key.trim().startsWith('context:')) {
+            return errorResult('Context is a reserved work-item artifact. Use record_context_exploration instead.');
+        }
+        if (!args.content)
+            return errorResult('update_artifact requires content.');
+        if (!Array.isArray(args.coverage) || args.coverage.length === 0) {
+            return errorResult('update_artifact requires repository coverage for every active project scope.');
+        }
+        for (const coverage of args.coverage) {
+            if (!coverage.repository_scope_id || !coverage.reason?.trim()) {
+                return errorResult('Every update_artifact coverage entry requires repository_scope_id and a non-empty reason.');
+            }
+            const unavailable = coverage.disposition === 'unavailable_acknowledged';
+            if (unavailable !== Boolean(coverage.acknowledgement_id)) {
+                return errorResult('update_artifact coverage acknowledgement_id is required only for unavailable_acknowledged repositories.');
+            }
+        }
+        const artifact = await must(deps.client.rpc('update_agent_artifact', {
+            p_run: agentRun.runId,
+            p_claim_fencing_token: agentRun.fencingToken,
+            p_topology_revision: agentRun.topologyRevision,
+            p_artifact: args.id,
+            p_expected_revision: args.expected_revision,
+            p_type: args.type,
+            p_format: args.format,
+            p_title: args.title.trim(),
+            p_purpose_key: args.purpose_key.trim(),
+            p_content: args.content,
+            p_coverage: args.coverage.map((coverage) => ({
+                repository_scope_id: coverage.repository_scope_id,
+                disposition: coverage.disposition,
+                reason: coverage.reason.trim(),
+                acknowledgement_id: coverage.acknowledgement_id ?? null,
+            })),
+        }));
+        if (!artifact)
+            throw new Error('update_agent_artifact returned no artifact');
+        return textResult({ artifact, repository_coverage: args.coverage });
+    }
+    catch (err) {
+        return coordinationError('update_artifact', err);
+    }
+}
 export async function addCommentHandler(deps, attribution, args, agentRunId) {
     try {
         if (!args.task_id)
@@ -1648,7 +1713,7 @@ export async function startMcpServer(deps) {
         return errorResult(`${tool} is blocked because this No workflow item has no instructions. ` +
             (run.noWorkflowIntent === 'missing'
                 ? 'Call ask_question with category intent to ask the user what should be done.'
-                : 'Persist the user\'s answer in the task description with update_task before continuing.'));
+                : 'Wait for the user to answer the decision in the web app, or record their conversational answer with record_user_input.'));
     }
     function buildServer(session) {
         const server = new McpServer({ name: 'ctrl-spc', version: BROKER_VERSION });
@@ -1783,7 +1848,7 @@ export async function startMcpServer(deps) {
                 reason: z.string().optional(),
                 persistence_receipt: z.object({
                     final_task_revision: z.number().int().positive(),
-                    artifact_ids: z.array(z.string()).min(1),
+                    artifact_ids: z.array(z.string()),
                     outcome: z.enum(['completed', 'blocked', 'aborted']).optional(),
                 }),
             },
@@ -1836,29 +1901,22 @@ export async function startMcpServer(deps) {
             if (missing)
                 return missing;
             const run = session.context.run;
-            if (!run.workflow?.enabled && run.noWorkflowIntent !== 'provided') {
-                if (run.noWorkflowIntent !== 'intent_question_asked') {
-                    return requireNoWorkflowIntent(session, 'update_task');
-                }
-                if (!args.fields.description?.trim() || Object.keys(args.fields).some(field => field !== 'description')) {
-                    return errorResult('After the No workflow intent question, update_task must first persist only the user\'s answer in the task description.');
-                }
-            }
+            const intent = requireNoWorkflowIntent(session, 'update_task');
+            if (intent)
+                return intent;
             const workflowError = workflowCapabilityError(run, 'update_task', 'update_task');
             if (workflowError)
                 return workflowError;
-            const result = await updateTaskHandler(bindProject(handlerDeps, run.projectId), attribution(), args, run);
-            if (!result.isError && !run.workflow?.enabled && run.noWorkflowIntent === 'intent_question_asked') {
-                run.noWorkflowIntent = 'provided';
-            }
-            return result;
+            return updateTaskHandler(bindProject(handlerDeps, run.projectId), attribution(), args, run);
         });
         server.registerTool('create_artifact', {
-            description: 'Persist an analysis/plan/spec/diagram/mock/wireframe on a task after context exploration. Never write planning documents into a repository.',
+            description: 'Create a titled analysis/plan/spec/diagram/mock/wireframe for a new stable purpose. Use update_artifact when that purpose already exists; a different purpose creates a different artifact.',
             inputSchema: {
                 task_id: z.string(),
                 type: z.enum(['analysis', 'plan', 'spec', 'diagram', 'mock', 'wireframe']),
                 format: z.enum(['md', 'html', 'json', 'svg']).optional().describe('Defaults to md'),
+                title: z.string().min(1),
+                purpose_key: z.string().min(1).describe('Stable machine-readable identity for this artifact purpose'),
                 content: z.string(),
                 coverage: z.array(z.object({
                     repository_scope_id: z.string(),
@@ -1880,12 +1938,44 @@ export async function startMcpServer(deps) {
                 return workflowError;
             return createArtifactHandler(bindProject(handlerDeps, run.projectId), attribution(), args, run);
         });
+        server.registerTool('update_artifact', {
+            description: 'Update the existing artifact for the same purpose. Pass its latest revision; stale updates conflict instead of creating a duplicate or overwriting newer work.',
+            inputSchema: {
+                id: z.string(),
+                expected_revision: z.number().int().positive(),
+                type: z.enum(['analysis', 'plan', 'spec', 'diagram', 'mock', 'wireframe']),
+                format: z.enum(['md', 'html', 'json', 'svg']),
+                title: z.string().min(1),
+                purpose_key: z.string().min(1),
+                content: z.string(),
+                coverage: z.array(z.object({
+                    repository_scope_id: z.string(),
+                    disposition: z.enum(['affected', 'reviewed_no_change', 'context_only', 'unavailable_acknowledged']),
+                    reason: z.string(),
+                    acknowledgement_id: z.string().nullable().optional(),
+                })).min(1).describe('Exactly one disposition for every active repository scope returned by get_task'),
+            },
+        }, async (args) => {
+            const missing = requireExploredSessionRun(session, 'update_artifact');
+            if (missing)
+                return missing;
+            const intent = requireNoWorkflowIntent(session, 'update_artifact');
+            if (intent)
+                return intent;
+            const run = session.context.run;
+            const workflowError = workflowCapabilityError(run, 'create_artifact', 'update_artifact');
+            if (workflowError)
+                return workflowError;
+            return updateArtifactHandler(bindProject(handlerDeps, run.projectId), args, run);
+        });
         server.registerTool('ask_question', {
             description: 'Persist a categorized, actionable question after complete context exploration. Questions are comments on the current work item.',
             inputSchema: {
                 task_id: z.string(),
                 category: z.enum(['clarification', 'reproduction', 'intent', 'dependency', 'checkout', 'collision', 'split']),
+                context: z.string().min(1).describe('Why this decision is needed and what it affects'),
                 question: z.string(),
+                related_artifact_id: z.string().nullable().optional(),
             },
         }, async (args) => {
             const missing = requireExploredSessionRun(session, 'ask_question');
@@ -1908,22 +1998,22 @@ export async function startMcpServer(deps) {
             return result;
         });
         server.registerTool('record_user_input', {
-            description: 'Persist the user\'s exact answer as an artifact and resolve the current workflow questions before continuing.',
+            description: 'Persist the user\'s exact answer on first-class decision records returned by ask_question. This creates no answer or approval artifact.',
             inputSchema: {
-                question_ids: z.array(z.string()).min(1),
+                decision_ids: z.array(z.string()).min(1).optional(),
+                question_ids: z.array(z.string()).min(1).optional().describe('Compatibility alias for decision_ids'),
                 answer: z.string(),
-                coverage: z.array(z.object({
-                    repository_scope_id: z.string(),
-                    disposition: z.enum(['affected', 'reviewed_no_change', 'context_only', 'unavailable_acknowledged']),
-                    reason: z.string(),
-                    acknowledgement_id: z.string().nullable().optional(),
-                })).min(1),
             },
         }, async (args) => {
             const missing = requireExploredSessionRun(session, 'record_user_input');
             if (missing)
                 return missing;
-            return recordUserInputHandler(handlerDeps, attribution(), session.context, args);
+            const result = await recordUserInputHandler(handlerDeps, attribution(), session.context, args);
+            const run = session.context.run;
+            if (!result.isError && run?.state === 'joined' && !run.workflow?.enabled && run.noWorkflowIntent === 'intent_question_asked') {
+                run.noWorkflowIntent = 'provided';
+            }
+            return result;
         });
         server.registerTool('submit_workflow_stage', {
             description: 'Submit the current workflow stage. The database validates its stored requirements and either advances or waits for user review.',
@@ -1972,6 +2062,7 @@ export async function startMcpServer(deps) {
             return askQuestionHandler(handlerDeps, attribution(), {
                 task_id: args.task_id,
                 category: 'clarification',
+                context: 'Legacy question recorded from add_comment.',
                 question: args.body,
             }, run);
         });

package/dist/protocol.js

@@ -87,7 +87,9 @@ is saved to the work item. I am applying the task's explicit intent gate now.”
    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.
+   unpersisted facts. Context has a stable purpose for the current workflow stage (or work
+   item without a workflow): repeat exploration updates that artifact instead of creating
+   another card.
 6. **Follow the workflow; otherwise ask exactly what is needed.** For an assigned workflow,
    the stored current-stage instructions and capabilities decide the work; never skip ahead
    based on task wording. Without a workflow, after exploration is recorded, classify intent
@@ -108,11 +110,11 @@ is saved to the work item. I am applying the task's explicit intent gate now.”
    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.** For workflow questions, call
-   \`record_user_input\` with the open question IDs and the user's exact answer; it creates
-   the required answer artifact before the stage continues. For no-workflow tasks, use
-   revision-safe \`update_task\` for accepted decisions and constraints. Immediately call \`update_task\`
-   after accepting a no-workflow answer so a later agent can recover it.
+7. **Persist every accepted answer and durable finding.** \`ask_question\` creates a
+   first-class decision and returns its decision ID for the web app to display and answer.
+   When the user answers in the agent conversation instead, call \`record_user_input\` with
+   those decision IDs and the user's exact answer. Decisions
+   are not answer artifacts and are not copied into the task description.
    Never leave an accepted answer or finding only in terminal, chat, or a subagent report.
 8. **Reserve the exact write surface only when allowed.** Read-only workflow stages never
    reserve write paths or edit files. When the current stage allows repository writes, call
@@ -124,16 +126,20 @@ is saved to the work item. I am applying the task's explicit intent gate now.”
 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 and submit every substantive non-question output.** Use \`create_artifact\` for every
+10. **Persist and submit every substantive non-question output.** Give each artifact a clear
+   title and stable \`purpose_key\`. Use \`create_artifact\` when that purpose does not exist and
+   \`update_artifact\` with the latest revision when the same purpose already exists; a
+   different purpose creates a different artifact. Persist 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. For workflow
    tasks, pass those artifact IDs and requirement roles to \`submit_workflow_stage\`; the
-   database alone decides whether the next stage starts or a review gate opens.
+   database alone decides whether the next stage starts or a review gate opens. Workflow
+   approval is displayed on the submitted plan; it is not a decision artifact.
 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
+   \`ask_question\`; accepted answers live in first-class decisions; 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
@@ -148,10 +154,10 @@ is saved to the work item. I am applying the task's explicit intent gate now.”
    rejected. Ending releases only this session's work.`;
 export const PROTOCOL_SHORT = 'ctrl-spc protocol (compact — full text: MCP prompt `ctrl-spc-protocol`): ' +
     'Workflow is authoritative: follow only get_task.workflow.current_stage instructions, capabilities, requirements, and gate. submit_workflow_stage cannot skip stages; requested changes stay in-stage; only final user approval sets Done. ' +
-    'For no-workflow unclear features only, MUST use ask_question and end blocked before doing unrequested work; never infer from findings. Generic goals improve, coordinate, prepare, and support are not deliverables. ' +
+    'No-workflow unclear feature: MUST ask_question, then end blocked; never infer from findings or call update_task/create_artifact/reserve_work_paths first. Improve, coordinate, prepare, support are not deliverables. ' +
     '1) get_task is read-only; begin_work (run coordinator) with exact prompt_instruction when supplied; 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) Workflow stage data decides intent. Without a workflow, intent comes only from task, prompt, and accepted answers—never from findings. ' +
-    '5) Workflow answers use record_user_input artifacts; no-workflow answers use revision-safe update_task. Persist every substantive output with create_artifact and every active scope covered. No progress comments or terminal-only findings. ' +
+    '5) record_context_exploration revises one task context across stages/agents. ask_question creates decisions answered in web; chat answers use record_user_input and create no answer artifact. Same purpose: update_artifact; different purpose: create_artifact. Plan approval stays on the plan, not in Decisions. Cover every active scope. No progress comments or terminal-only findings. ' +
     '6) Call reserve_work_paths only when the stage allows writes and target the exact checkout; never edit collisions. release_work_paths, then end_work with persistence_receipt={final_task_revision,artifact_ids,outcome}.';

package/dist/runtime-control.js

@@ -2,7 +2,10 @@ import { execFileSync, spawn } from 'node:child_process';
 import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync, rmSync, writeFileSync, } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { configDir } from './config.js';
+import { configDir, getMachineIdentity } from './config.js';
+export function brokerMatchesRuntime(health, kind, machineId) {
+    return health?.runtime?.kind === kind && health.machine_id === machineId;
+}
 const CURRENT_PACKAGE_PATH = fileURLToPath(new URL('../package.json', import.meta.url));
 const CURRENT_ENTRY_PATH = fileURLToPath(new URL('./index.js', import.meta.url));
 export const LOCAL_RUNTIME_PORT = Number(process.env.CTRL_SPC_LOCAL_PORT) || 4572;
@@ -209,8 +212,11 @@ export async function startRuntime(kind) {
             'Stop it from its terminal before switching connections.');
     }
     const currentHealth = await probeBroker(profile.port);
-    if (currentHealth?.runtime?.kind === kind)
-        return;
+    if (currentHealth?.runtime?.kind === kind) {
+        if (brokerMatchesRuntime(currentHealth, kind, getMachineIdentity().id))
+            return;
+        throw new Error('Another CTRL+SPC connection is already running for a different computer identity. Stop it and try again.');
+    }
     if (currentHealth) {
         throw new Error(`Port ${profile.port} is already used by an unlabeled process. Turn it off before continuing.`);
     }
@@ -242,10 +248,10 @@ export async function startRuntime(kind) {
         if (childExited)
             return true;
         const health = await probeBroker(profile.port);
-        return health?.runtime?.kind === kind;
+        return brokerMatchesRuntime(health, kind, getMachineIdentity().id);
     }, 30_000, 250);
     const health = await probeBroker(profile.port);
-    if (!ready || health?.runtime?.kind !== kind) {
+    if (!ready || !brokerMatchesRuntime(health, kind, getMachineIdentity().id)) {
         rmSync(pidPath(kind), { force: true });
         const log = existsSync(logPath(kind)) ? readFileSync(logPath(kind), 'utf8').trim().split('\n').slice(-4).join('\n') : '';
         throw new Error(`${profile.label} did not become ready.${log ? `\n${log}` : ''}`);

package/dist/skills.js

@@ -48,13 +48,13 @@ Before the context artifact exists, never state or imply a requested deliverable
 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 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 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.
+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\`. 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 — workflow answers MUST use \`record_user_input\` with open question IDs and the exact user answer so an artifact is saved. For No workflow, after every accepted answer, call revision-safe \`update_task\` to add the decision, constraint, acceptance criterion, and durable findings to the description. Do not use progress comments; do not leave findings only in the terminal.
+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 those decision IDs and the exact user answer. 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 output — call \`create_artifact\` for every substantive non-question output. Every artifact must have exactly one coverage disposition for every active repository scope. For workflow tasks, submit required artifact IDs and roles through \`submit_workflow_stage\`; the database decides whether to advance or wait for review. Never write planning documents into a repository.
+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, submit required artifact IDs and roles through \`submit_workflow_stage\`; the database decides whether to advance or wait for review. 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 are persisted through \`ask_question\`; every accepted answer and durable fact lives in the description; 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.
+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\`. Tools live at ${mcpUrl}.

package/dist/wake.js

@@ -0,0 +1,237 @@
+import { execFileSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getClient } from './supabase.js';
+import { getMachineIdentity } from './config.js';
+import { currentCompanionKind, runtimeStatuses, startRuntime, } from './runtime-control.js';
+const WAKE_LABEL = 'com.ctrl-spc.wake';
+const WAKE_INTERVAL_SECONDS = 60;
+const CURRENT_ENTRY_PATH = fileURLToPath(new URL('./index.js', import.meta.url));
+export const WAKE_REQUEST_FRESH_SECONDS = 150;
+const FAILED_CLEANUP_MINUTES = 10;
+export function wakeAgentPlistPath() {
+    return join(homedir(), 'Library', 'LaunchAgents', `${WAKE_LABEL}.plist`);
+}
+function xmlEscape(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+export function renderWakePlist(nodePath, entryPath, pathEnv) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${WAKE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xmlEscape(nodePath)}</string>
+    <string>${xmlEscape(entryPath)}</string>
+    <string>__wake-check</string>
+  </array>
+  <key>StartInterval</key><integer>${WAKE_INTERVAL_SECONDS}</integer>
+  <key>RunAtLoad</key><true/>
+  <key>ProcessType</key><string>Background</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key><string>${xmlEscape(pathEnv)}</string>
+  </dict>
+</dict>
+</plist>
+`;
+}
+function defaultLaunchctl(args) {
+    execFileSync('launchctl', args, { stdio: 'ignore' });
+}
+function defaultWrite(path, contents) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, contents, { mode: 0o644 });
+    chmodSync(path, 0o644);
+}
+function defaultRead(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+export function installWakeAgent(deps = {}) {
+    if (process.env.CTRL_SPC_NO_WAKE_AGENT === '1')
+        return false;
+    if (process.platform !== 'darwin' && !deps.plistPath)
+        return false;
+    const plistPath = deps.plistPath ?? wakeAgentPlistPath();
+    const contents = renderWakePlist(deps.nodePath ?? process.execPath, deps.entryPath ?? CURRENT_ENTRY_PATH, deps.pathEnv ?? process.env.PATH ?? '/usr/bin:/bin');
+    if ((deps.read ?? defaultRead)(plistPath) === contents)
+        return true;
+    (deps.write ?? defaultWrite)(plistPath, contents);
+    const uid = deps.uid ?? process.getuid?.();
+    if (uid === undefined)
+        return true;
+    const launchctl = deps.launchctl ?? defaultLaunchctl;
+    try {
+        launchctl(['bootout', `gui/${uid}`, plistPath]);
+    }
+    catch {
+        // The job was not loaded yet.
+    }
+    try {
+        launchctl(['bootstrap', `gui/${uid}`, plistPath]);
+    }
+    catch (error) {
+        // Do not leave a byte-identical plist behind after a failed bootstrap:
+        // installWakeAgent intentionally skips launchctl for identical files, so
+        // keeping it would make every later retry report success without loading
+        // the job.
+        try {
+            ;
+            (deps.remove ?? rmSync)(plistPath);
+        }
+        catch {
+            // Preserve the launchctl error, which is the actionable failure.
+        }
+        throw error;
+    }
+    return true;
+}
+export function removeWakeAgent(deps = {}) {
+    if (process.platform !== 'darwin' && !deps.plistPath)
+        return false;
+    const plistPath = deps.plistPath ?? wakeAgentPlistPath();
+    if (!(deps.exists ?? existsSync)(plistPath))
+        return false;
+    const uid = deps.uid ?? process.getuid?.();
+    if (uid !== undefined) {
+        try {
+            ;
+            (deps.launchctl ?? defaultLaunchctl)(['bootout', `gui/${uid}`, plistPath]);
+        }
+        catch {
+            // An unloaded job is already stopped; the file still needs removal.
+        }
+    }
+    ;
+    (deps.remove ?? rmSync)(plistPath);
+    return true;
+}
+export async function stampMachineHeartbeat(client, machineId, brokerRunning) {
+    const now = new Date().toISOString();
+    const patch = { waker_seen_at: now };
+    if (brokerRunning)
+        patch.broker_seen_at = now;
+    const { error } = await client.from('machines').update(patch).eq('id', machineId);
+    if (error)
+        throw error;
+}
+function assertNoError(error) {
+    if (error)
+        throw error;
+}
+function supabaseWakeDb(client, machineId) {
+    const table = () => client.from('machine_wake_requests');
+    const freshCutoff = () => new Date(Date.now() - WAKE_REQUEST_FRESH_SECONDS * 1000).toISOString();
+    return {
+        stampHeartbeat: (brokerRunning) => stampMachineHeartbeat(client, machineId, brokerRunning),
+        async claimFreshPending() {
+            const { data, error } = await table()
+                .select('id')
+                .eq('machine_id', machineId)
+                .eq('status', 'pending')
+                .gte('requested_at', freshCutoff())
+                .order('requested_at', { ascending: false })
+                .limit(1)
+                .maybeSingle();
+            assertNoError(error);
+            return data ?? null;
+        },
+        async failStalePending() {
+            const { error } = await table().update({
+                status: 'failed',
+                error: 'Request expired before this machine checked in.',
+                updated_at: new Date().toISOString(),
+            })
+                .eq('machine_id', machineId)
+                .eq('status', 'pending')
+                .lt('requested_at', freshCutoff());
+            assertNoError(error);
+        },
+        async resolvePending(id) {
+            const { error } = await table()
+                .delete()
+                .eq('id', id)
+                .eq('machine_id', machineId)
+                .eq('status', 'pending');
+            assertNoError(error);
+        },
+        async failRequest(id, message) {
+            const { error } = await table()
+                .update({ status: 'failed', error: message, updated_at: new Date().toISOString() })
+                .eq('id', id);
+            assertNoError(error);
+        },
+        async cleanupFailed() {
+            const cutoff = new Date(Date.now() - FAILED_CLEANUP_MINUTES * 60 * 1000).toISOString();
+            const { error } = await table()
+                .delete()
+                .eq('machine_id', machineId)
+                .eq('status', 'failed')
+                .lt('updated_at', cutoff);
+            assertNoError(error);
+        },
+    };
+}
+async function defaultGetDb() {
+    const client = await getClient();
+    return supabaseWakeDb(client, getMachineIdentity().id);
+}
+async function defaultBrokerRunning() {
+    const statuses = await runtimeStatuses();
+    const machineId = getMachineIdentity().id;
+    return statuses.some((status) => status.running && status.health?.machine_id === machineId);
+}
+export async function wakeCheck(deps = {}) {
+    try {
+        if (await (deps.brokerRunning ?? defaultBrokerRunning)())
+            return 'broker_running';
+    }
+    catch {
+        // A failed probe is treated as not running so the poller can recover it.
+    }
+    let db;
+    try {
+        db = await (deps.getDb ?? defaultGetDb)();
+    }
+    catch {
+        return 'no_session';
+    }
+    try {
+        await db.stampHeartbeat(false);
+        await db.failStalePending();
+        const pending = await db.claimFreshPending();
+        if (!pending) {
+            await db.cleanupFailed();
+            return 'idle';
+        }
+        try {
+            await (deps.start ?? startRuntime)((deps.runtimeKind ?? currentCompanionKind)());
+            await db.resolvePending(pending.id);
+            await db.stampHeartbeat(true);
+            await db.cleanupFailed();
+            return 'started';
+        }
+        catch (error) {
+            await db.failRequest(pending.id, error instanceof Error ? error.message : String(error));
+            await db.cleanupFailed();
+            return 'start_failed';
+        }
+    }
+    catch {
+        return 'idle';
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctrl-spc/cli",
-  "version": "1.3.4",
+  "version": "1.3.6",
   "description": "CTRL+SPC CLI — per-machine agent for browser login, project linking, presence, and the local MCP server.",
   "engines": {
     "node": ">=22"