specrails-desktop 2.29.1 → 2.29.2

package/server/dist/loop-runs-store.js

@@ -1,6 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createLoopRun = createLoopRun;
+exports.finishLoopRunAndJob = finishLoopRunAndJob;
+exports.listPendingLoopTerminalRecoveries = listPendingLoopTerminalRecoveries;
+exports.getLoopTerminalRecovery = getLoopTerminalRecovery;
+exports.completeLoopTerminalRecovery = completeLoopTerminalRecovery;
+exports.readLoopJobUsage = readLoopJobUsage;
+exports.stageLoopStepRecovery = stageLoopStepRecovery;
+exports.updateLoopStepEventCheckpoint = updateLoopStepEventCheckpoint;
+exports.updateLoopStepActivityCheckpoint = updateLoopStepActivityCheckpoint;
+exports.setLoopStepSettledResult = setLoopStepSettledResult;
+exports.getLoopStepRecovery = getLoopStepRecovery;
+exports.listLoopStepRecoveries = listLoopStepRecoveries;
+exports.completeLoopStepRecovery = completeLoopStepRecovery;
 exports.updateLoopRunCounters = updateLoopRunCounters;
 exports.finishLoopRun = finishLoopRun;
 exports.pauseLoopRun = pauseLoopRun;
@@ -16,11 +28,202 @@ function createLoopRun(db, input) {
     db.prepare(`
     INSERT INTO loop_runs (
       id, project_id, loop_id, loop_name, rail_index, ticket_id, provider, model,
-      reasoning_effort, status, iteration_limit, started_at
-    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'running', ?, ?)
-  `).run(input.id, input.projectId, input.loopId, input.loopName ?? null, input.railIndex ?? null, input.ticketId ?? null, input.provider ?? null, input.model ?? null, input.reasoningEffort ?? null, input.iterationLimit, input.startedAt);
+      reasoning_effort, ticket_ids_json, ticket_completion_status,
+      causal_ownership, status,
+      iteration_limit, started_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'running', ?, ?)
+  `).run(input.id, input.projectId, input.loopId, input.loopName ?? null, input.railIndex ?? null, input.ticketId ?? null, input.provider ?? null, input.model ?? null, input.reasoningEffort ?? null, JSON.stringify([...new Set(input.ticketIds ?? (input.ticketId == null ? [] : [input.ticketId]))]), input.ticketCompletionStatus ?? 'done', input.causalOwnership ? 1 : 0, input.iterationLimit, input.startedAt);
     return getLoopRun(db, input.id);
 }
+function parseTicketIdsJson(raw) {
+    try {
+        const parsed = JSON.parse(raw ?? '[]');
+        if (!Array.isArray(parsed))
+            return [];
+        return [...new Set(parsed.filter((id) => Number.isSafeInteger(id) && id > 0))];
+    }
+    catch {
+        return [];
+    }
+}
+/** Finalise the engine row, backing job and durable domain callback intent in
+ * one commit. A caller may crash anywhere after this returns; startup can still
+ * replay the exact launch ticket set without consulting an in-memory rail map. */
+function finishLoopRunAndJob(db, id, opts) {
+    const tx = db.transaction(() => {
+        const run = getLoopRun(db, id);
+        if (!run)
+            return undefined;
+        updateLoopRunCounters(db, id, opts.counters);
+        db.prepare(`
+      UPDATE loop_runs
+         SET status = 'completed', final_outcome = ?, finished_at = ?
+       WHERE id = ?
+    `).run(opts.outcome, opts.finishedAt, id);
+        db.prepare(`
+      UPDATE jobs
+         SET exit_code = ?, status = ?, finished_at = ?,
+             total_cost_usd = CASE WHEN EXISTS (
+               SELECT 1 FROM loop_step_recovery WHERE run_id = ?
+             ) THEN total_cost_usd ELSE ? END,
+             tokens_in = CASE WHEN EXISTS (
+               SELECT 1 FROM loop_step_recovery WHERE run_id = ?
+             ) THEN tokens_in ELSE ? END,
+             tokens_out = CASE WHEN EXISTS (
+               SELECT 1 FROM loop_step_recovery WHERE run_id = ?
+             ) THEN tokens_out ELSE ? END,
+             tokens_cache_read = CASE WHEN EXISTS (
+               SELECT 1 FROM loop_step_recovery WHERE run_id = ?
+             ) THEN tokens_cache_read ELSE ? END,
+             tokens_cache_create = CASE WHEN EXISTS (
+               SELECT 1 FROM loop_step_recovery WHERE run_id = ?
+             ) THEN tokens_cache_create ELSE ? END,
+             duration_ms = CASE WHEN EXISTS (
+               SELECT 1 FROM loop_step_recovery WHERE run_id = ?
+             ) THEN duration_ms ELSE ? END,
+             num_turns = CASE WHEN EXISTS (
+               SELECT 1 FROM loop_step_recovery WHERE run_id = ?
+             ) THEN num_turns ELSE ? END
+       WHERE id = ? AND owner = 'loop'
+    `).run(opts.job.exitCode, opts.job.status, opts.finishedAt, id, opts.job.totalCostUsd, id, opts.job.tokensIn, id, opts.job.tokensOut, id, opts.job.tokensCacheRead, id, opts.job.tokensCacheCreate, id, opts.job.durationMs, id, opts.job.numTurns, id);
+        const payload = {
+            version: 1,
+            runId: id,
+            projectId: run.project_id,
+            ticketIds: parseTicketIdsJson(run.ticket_ids_json),
+            railIndex: run.rail_index,
+            outcome: opts.callbackOutcome ?? opts.outcome,
+            jobStatus: opts.job.status,
+            ticketCompletionStatus: run.ticket_completion_status ?? 'done',
+            finishedAt: opts.finishedAt,
+            causalOwnership: run.causal_ownership === 1,
+            outcomeFinalized: opts.outcomeFinalized ?? true,
+        };
+        db.prepare(`
+      INSERT INTO loop_terminal_recovery (run_id, payload, callback_completed)
+      VALUES (?, ?, 0)
+      ON CONFLICT(run_id) DO UPDATE SET
+        payload = excluded.payload,
+        callback_completed = CASE
+          WHEN loop_terminal_recovery.callback_completed = 1 THEN 1 ELSE 0 END
+    `).run(id, JSON.stringify(payload));
+        return payload;
+    });
+    return tx();
+}
+function listPendingLoopTerminalRecoveries(db) {
+    return db.prepare(`
+    SELECT run_id, payload, callback_completed, created_at
+      FROM loop_terminal_recovery
+     WHERE callback_completed = 0
+     ORDER BY created_at, run_id
+  `).all();
+}
+function getLoopTerminalRecovery(db, runId) {
+    return db.prepare(`SELECT * FROM loop_terminal_recovery WHERE run_id = ?`).get(runId);
+}
+function completeLoopTerminalRecovery(db, runId) {
+    db.prepare(`UPDATE loop_terminal_recovery SET callback_completed = 1 WHERE run_id = ?`).run(runId);
+    db.prepare(`DELETE FROM loop_terminal_recovery WHERE run_id = ? AND callback_completed = 1`).run(runId);
+}
+function readLoopJobUsage(db, runId) {
+    const row = db.prepare(`
+    SELECT tokens_in, tokens_out, tokens_cache_read, tokens_cache_create,
+           total_cost_usd, num_turns
+      FROM jobs WHERE id = ?
+  `).get(runId);
+    return {
+        tokensIn: row?.tokens_in ?? 0,
+        tokensOut: row?.tokens_out ?? 0,
+        tokensCacheRead: row?.tokens_cache_read ?? 0,
+        tokensCacheCreate: row?.tokens_cache_create ?? 0,
+        totalCostUsd: row?.total_cost_usd ?? 0,
+        numTurns: row?.num_turns ?? 0,
+    };
+}
+function stageLoopStepRecovery(db, payload) {
+    db.prepare(`
+    INSERT INTO loop_step_recovery (run_id, step_key, invocation_id, payload)
+    VALUES (?, ?, ?, ?)
+    ON CONFLICT(run_id, step_key) DO NOTHING
+  `).run(payload.runId, payload.stepKey, payload.invocationId, JSON.stringify(payload));
+}
+function updateLoopStepEventCheckpoint(db, runId, stepKey, completedEventSeq, providerCostBaseline, providerTurnsBaseline, completedDurationMs) {
+    const row = db.prepare(`SELECT payload FROM loop_step_recovery WHERE run_id = ? AND step_key = ?`)
+        .get(runId, stepKey);
+    if (!row)
+        throw new Error(`Missing loop step checkpoint ${runId}/${stepKey}`);
+    const payload = JSON.parse(row.payload);
+    payload.completedEventSeq = Math.max(payload.completedEventSeq, completedEventSeq);
+    if (providerCostBaseline !== undefined)
+        payload.providerCostBaseline = providerCostBaseline;
+    if (providerTurnsBaseline !== undefined)
+        payload.providerTurnsBaseline = providerTurnsBaseline;
+    if (completedDurationMs !== undefined) {
+        payload.completedDurationMs = completedDurationMs;
+        // The completed duration now includes this turn. Leaving its active segment
+        // behind would make a later no-result recovery count it twice.
+        delete payload.activeTurnStartedAtMs;
+        delete payload.lastActivityAtMs;
+    }
+    db.prepare(`UPDATE loop_step_recovery SET payload = ? WHERE run_id = ? AND step_key = ?`)
+        .run(JSON.stringify(payload), runId, stepKey);
+}
+/** Persist the active turn's wall-clock bounds without advancing the raw-event
+ * frontier. A result checkpoint later clears this segment in the same update
+ * that commits completedDurationMs. */
+function updateLoopStepActivityCheckpoint(db, runId, stepKey, turnStartedAtMs, activityAtMs) {
+    const row = db.prepare(`SELECT payload FROM loop_step_recovery WHERE run_id = ? AND step_key = ?`)
+        .get(runId, stepKey);
+    if (!row)
+        throw new Error(`Missing loop step checkpoint ${runId}/${stepKey}`);
+    const payload = JSON.parse(row.payload);
+    if (!Number.isFinite(activityAtMs))
+        throw new Error('Loop step activity timestamp must be finite');
+    const requestedStart = Number.isFinite(turnStartedAtMs)
+        ? Math.max(0, Math.trunc(turnStartedAtMs))
+        : undefined;
+    const startedAt = requestedStart ?? payload.activeTurnStartedAtMs ?? Math.max(0, Math.trunc(activityAtMs));
+    const activityAt = Math.max(startedAt, Math.trunc(activityAtMs));
+    payload.activeTurnStartedAtMs = requestedStart ?? payload.activeTurnStartedAtMs ?? startedAt;
+    payload.lastActivityAtMs = Math.max(payload.lastActivityAtMs ?? startedAt, activityAt);
+    db.prepare(`UPDATE loop_step_recovery SET payload = ? WHERE run_id = ? AND step_key = ?`)
+        .run(JSON.stringify(payload), runId, stepKey);
+}
+function setLoopStepSettledResult(db, runId, stepKey, settledResult) {
+    const row = db.prepare(`SELECT payload FROM loop_step_recovery WHERE run_id = ? AND step_key = ?`)
+        .get(runId, stepKey);
+    if (!row)
+        throw new Error(`Missing loop step checkpoint ${runId}/${stepKey}`);
+    const payload = JSON.parse(row.payload);
+    payload.settledResult = settledResult;
+    db.prepare(`UPDATE loop_step_recovery SET payload = ? WHERE run_id = ? AND step_key = ?`)
+        .run(JSON.stringify(payload), runId, stepKey);
+}
+function getLoopStepRecovery(db, runId, stepKey) {
+    return db.prepare(`SELECT * FROM loop_step_recovery WHERE run_id = ? AND step_key = ?`)
+        .get(runId, stepKey);
+}
+function listLoopStepRecoveries(db) {
+    return db.prepare(`SELECT * FROM loop_step_recovery ORDER BY created_at, run_id, step_key`).all();
+}
+/** Execute the invocation insert and checkpoint removal under one SQLite
+ * transaction. If either statement fails, neither survives. */
+function completeLoopStepRecovery(db, runId, stepKey, record) {
+    const tx = db.transaction(() => {
+        const row = getLoopStepRecovery(db, runId, stepKey);
+        if (!row)
+            return false;
+        const payload = JSON.parse(row.payload);
+        record(payload);
+        const removed = db.prepare(`DELETE FROM loop_step_recovery WHERE run_id = ? AND step_key = ?`)
+            .run(runId, stepKey);
+        if (removed.changes !== 1)
+            throw new Error(`loop step checkpoint ${runId}/${stepKey} was not removed`);
+        return true;
+    });
+    return tx();
+}
 // Column allow-list — counters are interpolated into the SET clause, so gate
 // the keys to prevent any future caller injecting SQL via an object key.
 const COUNTER_COLUMNS = {
@@ -126,14 +329,64 @@ function countRunningForLoop(db, loopId) {
 }
 /** Reconcile orphan runs at startup: any row still active belongs to a process
  *  that is now dead (server restart, or a run killed before it could settle), so
- *  mark it terminal (`completed` + outcome `failed`). A paused row is active too:
- *  its resumable context lived in the old process. Without this an orphan keeps
- *  `countRunningForLoop > 0` forever, which wedges the loop as un-editable /
- *  un-publishable ("Failed to save loop" via the isRunning 409). Returns the
- *  number of rows reconciled. */
-function reconcileOrphanLoopRuns(db, finishedAt) {
-    const res = db
-        .prepare(`UPDATE loop_runs SET status = 'completed', final_outcome = COALESCE(final_outcome, 'failed'), finished_at = COALESCE(finished_at, ?) WHERE status IN ('running','paused')`)
-        .run(finishedAt);
-    return res.changes ?? 0;
+ *  mark it terminal (`completed` + outcome `failed`). Its loop-owned backing
+ *  jobs row is failed in the SAME transaction. QueueManager deliberately does
+ *  not sweep those rows: LoopRunManager is the sole invocation authority, so
+ *  treating the accumulated step total as a second surface='job' invocation
+ *  would double-count spend. A paused row is active too: its resumable context
+ *  lived in the old process. Returns the number of loop rows reconciled. */
+function reconcileOrphanLoopRuns(db, finishedAt, 
+/** Compatibility only for pre-migration rows whose exact launch ticket set
+ * was never persisted. New rows always use ticket_ids_json. */
+legacyTicketIdsByRun) {
+    const reconcile = db.transaction(() => {
+        const active = db.prepare(`
+      SELECT * FROM loop_runs WHERE status IN ('running', 'paused')
+    `).all();
+        if (active.length === 0)
+            return 0;
+        const updateJob = db.prepare(`
+      UPDATE jobs
+         SET status = 'failed', exit_code = -1,
+             finished_at = COALESCE(finished_at, ?),
+             duration_ms = COALESCE(
+               (SELECT total_duration_ms FROM loop_runs WHERE loop_runs.id = jobs.id),
+               duration_ms
+             )
+       WHERE owner = 'loop' AND status = 'running' AND id = ?
+    `);
+        const updateRun = db.prepare(`
+      UPDATE loop_runs
+         SET status = 'completed', final_outcome = 'failed',
+             finished_at = COALESCE(finished_at, ?)
+       WHERE id = ? AND status IN ('running', 'paused')
+    `);
+        const insertIntent = db.prepare(`
+      INSERT INTO loop_terminal_recovery (run_id, payload, callback_completed)
+      VALUES (?, ?, 0)
+      ON CONFLICT(run_id) DO NOTHING
+    `);
+        for (const run of active) {
+            updateJob.run(finishedAt, run.id);
+            updateRun.run(finishedAt, run.id);
+            const persistedIds = parseTicketIdsJson(run.ticket_ids_json);
+            const legacyIds = legacyTicketIdsByRun?.get(run.id) ?? [];
+            const payload = {
+                version: 1,
+                runId: run.id,
+                projectId: run.project_id,
+                ticketIds: persistedIds.length > 0 ? persistedIds : [...new Set(legacyIds)],
+                railIndex: run.rail_index,
+                outcome: 'failed',
+                jobStatus: 'failed',
+                ticketCompletionStatus: run.ticket_completion_status ?? 'done',
+                finishedAt,
+                causalOwnership: run.causal_ownership === 1,
+                outcomeFinalized: true,
+            };
+            insertIntent.run(run.id, JSON.stringify(payload));
+        }
+        return active.length;
+    });
+    return reconcile();
 }

package/server/dist/mcp/agent-capability.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mintAgentCapability = mintAgentCapability;
+exports.verifyAgentCapability = verifyAgentCapability;
+exports.revokeAgentCapability = revokeAgentCapability;
+exports._resetAgentCapabilitiesForTest = _resetAgentCapabilitiesForTest;
+const crypto_1 = require("crypto");
+const DEFAULT_TTL_MS = 6 * 60 * 60 * 1000;
+const MAX_TTL_MS = DEFAULT_TTL_MS;
+const CONVERSATION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+const capabilities = new Map();
+function tokenHash(token) {
+    return (0, crypto_1.createHash)('sha256').update(token).digest('hex');
+}
+function pruneExpired(now = Date.now()) {
+    for (const [hash, capability] of capabilities) {
+        if (capability.expiresAt <= now)
+            capabilities.delete(hash);
+    }
+}
+function headerToken(value) {
+    const raw = Array.isArray(value) ? value[0] : value;
+    if (typeof raw !== 'string')
+        return null;
+    const token = raw.trim();
+    return token.length >= 32 && token.length <= 256 ? token : null;
+}
+/**
+ * Mint an in-memory, per-turn capability. Only the hash is retained server-side;
+ * callers must revoke the returned secret when the owning AI process settles.
+ */
+function mintAgentCapability(input) {
+    if (!CONVERSATION_ID_RE.test(input.conversationId)) {
+        throw new Error(`unsafe agent conversation id: ${input.conversationId}`);
+    }
+    const ttl = Number.isFinite(input.ttlMs) && input.ttlMs > 0
+        ? Math.min(Math.trunc(input.ttlMs), MAX_TTL_MS)
+        : DEFAULT_TTL_MS;
+    const now = Date.now();
+    pruneExpired(now);
+    const token = (0, crypto_1.randomBytes)(32).toString('base64url');
+    capabilities.set(tokenHash(token), {
+        conversationId: input.conversationId,
+        projectId: input.projectId?.trim() || null,
+        tierLevel: input.tierLevel,
+        expiresAt: now + ttl,
+    });
+    return token;
+}
+/** Resolve only capabilities minted by this process and still inside their TTL. */
+function verifyAgentCapability(value) {
+    const token = headerToken(value);
+    if (!token)
+        return null;
+    const now = Date.now();
+    pruneExpired(now);
+    const found = capabilities.get(tokenHash(token));
+    if (!found || found.expiresAt <= now)
+        return null;
+    return { ...found };
+}
+/** Revoke a turn capability immediately; safe to call more than once. */
+function revokeAgentCapability(token) {
+    if (!token)
+        return;
+    capabilities.delete(tokenHash(token));
+}
+/** Test seam: capabilities are process-local and must never bleed between cases. */
+function _resetAgentCapabilitiesForTest() {
+    capabilities.clear();
+}

package/server/dist/mcp/guide.js

@@ -150,8 +150,11 @@ heading inside the description); \`labels\`; \`priority\`. Spec content is Engli
   slash-command job (e.g. \`/specrails:implement #5 --yes\`); \`queue\`, \`pause\`,
   \`resume\`, \`reorder\`, \`priority\` manage the queue.
 - Long-running shell commands launched with \`specrails_jobs(background_start)\`
-  create chat chips; use \`specrails_jobs(background_logs, pid)\` to read bounded
-  stdout/stderr tail when a chip exits or fails.
+  create chat chips. Start/kill are destructive and available only to an
+  authenticated in-app Agent turn at Autonomous level after explicit user
+  confirmation; third-party MCP clients cannot invoke them. Use
+  \`specrails_jobs(background_logs, pid)\` to read bounded stdout/stderr tail
+  when a chip exits or fails.
 
 ## Async results (IMPORTANT)
 

package/server/dist/mcp/mcp-server.js

@@ -12,6 +12,7 @@ const desktop_db_1 = require("../desktop-db");
 const catalog_1 = require("./tools/catalog");
 const types_1 = require("./tools/types");
 const resources_1 = require("./resources");
+const agent_capability_1 = require("./agent-capability");
 function jsonRpcError(message, code = -32000) {
     return { jsonrpc: '2.0', error: { code, message }, id: null };
 }
@@ -89,16 +90,10 @@ class McpServerManager {
      * carry the `mcp-session-id` header.
      */
     async handleHttp(req, res) {
-        // The external Settings ▸ MCP toggle gates THIRD-PARTY clients only. The
-        // in-app agent chat is first-party: it reaches this loopback endpoint through
-        // the bundled bridge, which always forwards the `x-specrails-agent-tier`
-        // header. Serving that request regardless of the toggle means the in-app
-        // agent gets its MCP by default with zero config on a fresh install (the
-        // toggle defaults OFF). Third-party clients (no agent-tier header) still get
-        // 404 until the user explicitly opts in. Both paths already sit behind
-        // requireLoopback + requireMcpAuth (scoped token), so this is not an auth
-        // relaxation — only the enable-toggle is bypassed for the first-party agent.
-        const isFirstPartyAgent = Boolean(req.headers[agent_tier_1.AGENT_TIER_HEADER]);
+        // The external Settings toggle gates third-party clients. Only a live,
+        // server-minted per-turn capability identifies the in-app agent and may
+        // bypass it; caller-authored context headers grant no authority.
+        const isFirstPartyAgent = (0, agent_capability_1.verifyAgentCapability)(req.headers[agent_tier_1.AGENT_CAPABILITY_HEADER]) !== null;
         if (!this.isEnabledSetting() && !isFirstPartyAgent) {
             res.status(404).json(jsonRpcError('MCP is disabled. Enable it in the Specrails app under Settings ▸ MCP.', -32004));
             return;

package/server/dist/mcp/mcp-token.js

@@ -8,11 +8,11 @@ exports.getMcpToken = getMcpToken;
 exports.regenerateMcpToken = regenerateMcpToken;
 exports.requireMcpAuth = requireMcpAuth;
 exports._resetMcpTokenForTest = _resetMcpTokenForTest;
-const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
 const crypto_1 = require("crypto");
 const auth_1 = require("../auth");
+const secure_token_file_1 = require("../util/secure-token-file");
 // ─── MCP-scoped token (design D3) ─────────────────────────────────────────────
 //
 // The MCP surface is authenticated by a token SEPARATE from the all-powerful
@@ -49,8 +49,9 @@ function loadOrGenerateMcpToken() {
     if (_mcpToken)
         return _mcpToken;
     try {
-        if (fs_1.default.existsSync(tokenPath())) {
-            const t = fs_1.default.readFileSync(tokenPath(), 'utf-8').trim();
+        const stored = (0, secure_token_file_1.readPrivateTextFile)(tokenPath());
+        if (stored !== null) {
+            const t = stored.trim();
             if (t && t.length >= 32) {
                 _mcpToken = t;
                 return _mcpToken;
@@ -66,8 +67,7 @@ function loadOrGenerateMcpToken() {
 }
 function persist(token) {
     try {
-        fs_1.default.mkdirSync(tokenDir(), { recursive: true });
-        fs_1.default.writeFileSync(tokenPath(), token, { encoding: 'utf-8', mode: 0o600 });
+        (0, secure_token_file_1.writePrivateTextFile)(tokenPath(), token);
     }
     catch (err) {
         console.warn('[mcp] could not persist mcp token to disk:', err);

package/server/dist/mcp/tools/jobs.js

@@ -17,6 +17,12 @@ function resolveBackgroundCwd(projectRoot, cwd) {
     }
     return resolved;
 }
+function requireFirstPartyConversation(ctx, action) {
+    if (!ctx.firstPartyAgent || !ctx.originConversationId) {
+        throw new Error(`${action} is available only to an authenticated in-app agent turn.`);
+    }
+    return ctx.originConversationId;
+}
 function backgroundHooks(broadcast) {
     return {
         onStarted: (process) => broadcast({
@@ -64,8 +70,8 @@ function jobsTools() {
             title: 'Jobs & Queue',
             description: 'Manage a project\'s AI-pipeline job queue and individual jobs. ' +
                 'Actions: list, get, queue, spawn (ai-spawn — enqueues an arbitrary slash-command job, returns {jobId,position}, async; from the in-app agent chat the engine defaults to your conversation\'s provider — pass aiEngine to override), ' +
-                'background_start (operate-level shell command tied to the current agent chat; requires confirmed:true after explicit user confirmation before use), background_logs, background_kill, ' +
-                'cancel (destructive — cancels a running/queued job or deletes a terminal one), ' +
+                'background_start (in-app-agent-only destructive shell command tied to the authenticated chat; requires confirmed:true after explicit user confirmation), background_logs, background_kill (in-app-agent-only destructive), ' +
+                'cancel (destructive — requests cancellation of a running/queued job; it does not delete terminal history), ' +
                 'purge (destructive — bulk-delete persisted job rows in a date range), ' +
                 'pause / resume (queue), reorder (queued-job order), priority (change a queued job\'s priority), ' +
                 'compare (two jobs side-by-side), export (up to 10k rows as JSON/CSV — inlines everything; prefer list/stats for token economy), ' +
@@ -77,9 +83,9 @@ function jobsTools() {
             hintTier: 'read',
             tier: (a) => {
                 const action = a.action;
-                if (['cancel', 'purge'].includes(action))
+                if (['cancel', 'purge', 'background_start', 'background_kill'].includes(action))
                     return 'destructive';
-                if (['spawn', 'interactive_turn', 'background_start', 'background_kill'].includes(action))
+                if (['spawn', 'interactive_turn'].includes(action))
                     return 'ai-spawn';
                 if (['pause', 'resume', 'reorder', 'priority', 'finalize'].includes(action))
                     return 'write';
@@ -147,7 +153,7 @@ function jobsTools() {
                     .describe('reorder: exact set of currently-queued job ids in the desired order; compare: exactly 2 job ids'),
                 // ── interactive_turn ──
                 text: zod_1.z.string().optional().describe('Prompt text for interactive_turn'),
-                chatId: zod_1.z.string().optional().describe('Agent chat conversation id for background_start/background_logs/background_kill ownership; defaults to the in-app agent conversation that called the tool'),
+                chatId: zod_1.z.string().optional().describe('Conversation id for background_logs ownership. background_start/background_kill ignore this field and use the authenticated in-app capability.'),
                 cwd: zod_1.z.string().optional().describe('Optional cwd for background_start; resolved inside the selected project root'),
                 pid: zod_1.z.number().optional().describe('Background process pid for background_logs/background_kill'),
                 confirmed: zod_1.z.boolean().optional().describe('background_start only: must be true after explicit user confirmation for this exact command'),
@@ -214,7 +220,7 @@ function jobsTools() {
                         const id = args.jobId;
                         if (!id)
                             throw new Error('cancel requires a "jobId".');
-                        return (0, types_1.apiCall)(ctx, 'DELETE', `${base}/jobs/${encodeURIComponent(id)}`);
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/jobs/${encodeURIComponent(id)}/cancel`);
                     }
                     case 'purge':
                         return (0, types_1.apiCall)(ctx, 'DELETE', `${base}/jobs`, {
@@ -329,9 +335,7 @@ function jobsTools() {
                             throw new Error('background_start requires a "command".');
                         if (args.confirmed !== true)
                             throw new Error('background_start requires confirmed:true after explicit user confirmation for this exact command.');
-                        const chatId = args.chatId ?? ctx.originConversationId ?? undefined;
-                        if (!chatId || !chatId.trim())
-                            throw new Error('background_start requires a "chatId".');
+                        const chatId = requireFirstPartyConversation(ctx, 'background_start');
                         const projectCtx = (0, types_1.requireProject)(ctx, args.projectId);
                         const busyReason = backgroundStartBusyReason(projectCtx);
                         if (busyReason && args.allowWhileBusy !== true) {
@@ -345,9 +349,7 @@ function jobsTools() {
                         const pid = args.pid;
                         if (typeof pid !== 'number' || !Number.isFinite(pid))
                             throw new Error('background_kill requires a numeric "pid".');
-                        const chatId = args.chatId ?? ctx.originConversationId ?? undefined;
-                        if (!chatId || !chatId.trim())
-                            throw new Error('background_kill requires a "chatId".');
+                        const chatId = requireFirstPartyConversation(ctx, 'background_kill');
                         const projectCtx = (0, types_1.requireProject)(ctx, args.projectId);
                         const killed = (0, transient_children_1.killOwnedBackgroundProcess)(pid, { projectId: projectCtx.project.id, chatId: chatId.trim() });
                         if (!killed)
@@ -358,7 +360,12 @@ function jobsTools() {
                         const pid = args.pid;
                         if (typeof pid !== 'number' || !Number.isFinite(pid))
                             throw new Error('background_logs requires a numeric "pid".');
-                        const chatId = args.chatId ?? ctx.originConversationId ?? undefined;
+                        // A first-party turn is confined to its authenticated conversation
+                        // for reads as well as start/kill. External read-tier clients still
+                        // supply chatId explicitly because they have no agent capability.
+                        const chatId = ctx.firstPartyAgent
+                            ? requireFirstPartyConversation(ctx, 'background_logs')
+                            : args.chatId;
                         if (!chatId || !chatId.trim())
                             throw new Error('background_logs requires a "chatId".');
                         const projectCtx = (0, types_1.requireProject)(ctx, args.projectId);

package/server/dist/mcp/tools/types.js

@@ -11,9 +11,7 @@ const mcp_tiers_1 = require("../mcp-tiers");
 const auth_1 = require("../../auth");
 const agent_tier_1 = require("../../agent-tier");
 const agent_store_1 = require("../../agent-store");
-/** Launch-route contract for an origin conversation id — must match the
- *  rails-router validation so a sanitized id is never 400'd downstream. */
-const ORIGIN_CONVERSATION_ID_RE = /^[A-Za-z0-9-]{1,64}$/;
+const agent_capability_1 = require("../agent-capability");
 /**
  * Calls the app's own REST API over loopback using the MASTER token (held
  * server-side, never exposed to the MCP client). This reuses every router's
@@ -51,7 +49,7 @@ function projectPath(ctx, projectId) {
 }
 /**
  * Launch defaults derived from the LAUNCHING agent-chat conversation (the
- * origin header carried on `ctx.originConversationId`). When the in-app agent
+ * authenticated origin carried on `ctx.originConversationId`). When the in-app agent
  * drives a rail launch / job spawn WITHOUT an explicit engine, the job must
  * run on the CONVERSATION's provider — a codex conversation asking to
  * implement must not silently launch claude via the router's fall-through to
@@ -91,16 +89,15 @@ function requireProject(ctx, projectId) {
 }
 // ── Active-project stickiness (per server process) ────────────────────────────
 // The active project is a soft default; an explicit projectId always wins, and
-// a per-request pin (ctx.requestProjectId, from the in-app agent's loopback
-// header) wins over the process-wide selection. `setActiveProject` remains for
-// `specrails_select_project` (and, fallback-only, the agent-chat manager's
-// per-turn pin) — request headers must never mutate this global.
+// a per-request pin (ctx.requestProjectId, from the verified in-app capability)
+// wins over the process-wide selection. `setActiveProject` remains for
+// `specrails_select_project`; request context must never mutate this global.
 let _activeProjectId = null;
 function setActiveProject(id) {
     _activeProjectId = id;
 }
 function getActiveProject(ctx) {
-    return ctx.requestProjectId ?? _activeProjectId;
+    return ctx.requestProjectId !== undefined ? ctx.requestProjectId : _activeProjectId;
 }
 function tierAnnotations(tier) {
     switch (tier) {
@@ -161,40 +158,21 @@ function registerTieredTool(server, ctx, spec) {
         inputSchema: spec.inputSchema,
         annotations: tierAnnotations(hintTier),
     }, async (args, extra) => {
-        // In-app agent: a per-request active-project header (loopback-only, set by
-        // the agent's bridge from the Cursor-style selector) pins the project for
-        // THIS CALL ONLY via a per-call ctx copy — it must never mutate the
-        // process-wide active project, or a concurrent external MCP client and the
-        // in-app agent would clobber each other (wrong-project delete/launch).
-        const projectHeader = extra?.requestInfo?.headers?.[agent_tier_1.AGENT_PROJECT_HEADER];
-        let callCtx = ctx;
-        if (projectHeader != null) {
-            const pid = Array.isArray(projectHeader) ? projectHeader[0] : projectHeader;
-            if (typeof pid === 'string' && pid.trim())
-                callCtx = { ...ctx, requestProjectId: pid.trim() };
-        }
-        // Origin link (safe-pr-review-flow): the in-app agent's bridge forwards its
-        // conversation id so a rail launched by THIS CALL can be tagged with its
-        // origin. Same per-call copy discipline as the project header — and it must
-        // spread callCtx (not ctx) so a coexisting project pin is never dropped.
-        // Malformed ids sanitize to null (never throw — the launch degrades to
-        // untagged rather than failing the tool call).
-        const convHeader = extra?.requestInfo?.headers?.[agent_tier_1.AGENT_CONVERSATION_HEADER];
-        if (convHeader != null) {
-            const cid = Array.isArray(convHeader) ? convHeader[0] : convHeader;
-            const trimmed = typeof cid === 'string' ? cid.trim() : '';
-            callCtx = {
-                ...callCtx,
-                originConversationId: trimmed && ORIGIN_CONVERSATION_ID_RE.test(trimmed) ? trimmed : null,
-            };
-        }
+        // Loopback identifies a machine, not a trusted caller. All first-party
+        // authority and context come from this unguessable, server-minted bearer;
+        // legacy tier/project/conversation headers are deliberately ignored.
+        const capability = (0, agent_capability_1.verifyAgentCapability)(extra?.requestInfo?.headers?.[agent_tier_1.AGENT_CAPABILITY_HEADER]);
+        const callCtx = capability
+            ? {
+                ...ctx,
+                requestProjectId: capability.projectId,
+                originConversationId: capability.conversationId,
+                firstPartyAgent: true,
+            }
+            : ctx;
         const tier = typeof spec.tier === 'function' ? spec.tier(args ?? {}) : spec.tier;
-        // In-app agent: when the request carries the loopback-only agent-tier header,
-        // enforce the cumulative ladder instead of the external Settings checkboxes
-        // (design D4). Absent header → external client → unchanged Settings gate.
-        const agentLevel = (0, agent_tier_1.levelFromHeader)(extra?.requestInfo?.headers?.[agent_tier_1.AGENT_TIER_HEADER]);
-        if (agentLevel !== null) {
-            if (!(0, agent_tier_1.levelAllowsTier)(agentLevel, tier)) {
+        if (capability) {
+            if (!(0, agent_tier_1.levelAllowsTier)(capability.tierLevel, tier)) {
                 return errorResult((0, mcp_tiers_1.tierRefusalMessage)(tier));
             }
         }

package/server/dist/mobile/mobile-router.js

@@ -232,7 +232,7 @@ function createMobileRouter(deps) {
         const pid = seg(req.params.pid), jid = seg(req.params.jid);
         if (!validate(res, [pid, PID_RE], [jid, JOBID_RE]))
             return;
-        void forward(res, 'DELETE', `/api/projects/${encodeURIComponent(pid)}/jobs/${encodeURIComponent(jid)}`, '');
+        void forward(res, 'POST', `/api/projects/${encodeURIComponent(pid)}/jobs/${encodeURIComponent(jid)}/cancel`, '');
     });
     v1.post('/projects/:pid/queue/pause', (req, res) => {
         const pid = seg(req.params.pid);