specrails-desktop 2.32.0 → 2.33.0

package/client/dist/index.html

@@ -204,7 +204,7 @@
         .specrails-splash__mark .pill { opacity: 1; }
       }
     </style>
-    <script type="module" crossorigin src="/assets/index-kCUcnT8G.js"></script>
+    <script type="module" crossorigin src="/assets/index-Bpzm94S9.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-CNC7AqOf.js">
     <link rel="modulepreload" crossorigin href="/assets/jsx-runtime-zu2_FqZY.js">
     <link rel="modulepreload" crossorigin href="/assets/react-dom-DiWzBDP9.js">
@@ -215,7 +215,7 @@
     <link rel="modulepreload" crossorigin href="/assets/addspec-x3mizDxc.js">
     <link rel="modulepreload" crossorigin href="/assets/agent-Bs9NilfI.js">
     <link rel="modulepreload" crossorigin href="/assets/agents-ms7TwG16.js">
-    <link rel="modulepreload" crossorigin href="/assets/agentstudio-Bz169Vzt.js">
+    <link rel="modulepreload" crossorigin href="/assets/agentstudio-CN2pokQu.js">
     <link rel="modulepreload" crossorigin href="/assets/aiedit-iIjz2_Qk.js">
     <link rel="modulepreload" crossorigin href="/assets/analytics-BHqUazhP.js">
     <link rel="modulepreload" crossorigin href="/assets/attachments-B53PG733.js">
@@ -234,23 +234,23 @@
     <link rel="modulepreload" crossorigin href="/assets/mcp-uDkXYu4L.js">
     <link rel="modulepreload" crossorigin href="/assets/nav-VaB-C4k5.js">
     <link rel="modulepreload" crossorigin href="/assets/settings-CuVwOpe0.js">
-    <link rel="modulepreload" crossorigin href="/assets/setup-DwcQ921P.js">
+    <link rel="modulepreload" crossorigin href="/assets/setup-D73npsqO.js">
     <link rel="modulepreload" crossorigin href="/assets/specs-DII0C8gw.js">
     <link rel="modulepreload" crossorigin href="/assets/terminal-BFRZnMPP.js">
     <link rel="modulepreload" crossorigin href="/assets/tickets-CqqOHbli.js">
-    <link rel="modulepreload" crossorigin href="/assets/i18n-Ch-Db_x2.js">
-    <link rel="modulepreload" crossorigin href="/assets/Trans-B2i5HVcM.js">
+    <link rel="modulepreload" crossorigin href="/assets/i18n-B2SaZsf2.js">
+    <link rel="modulepreload" crossorigin href="/assets/Trans-CpUoGvNy.js">
     <link rel="modulepreload" crossorigin href="/assets/dist-bVqfYmby.js">
     <link rel="modulepreload" crossorigin href="/assets/arrow-left-CpIR4j7G.js">
     <link rel="modulepreload" crossorigin href="/assets/auth-D_5bQv5W.js">
     <link rel="modulepreload" crossorigin href="/assets/api-B2M7CtDw.js">
-    <link rel="modulepreload" crossorigin href="/assets/useBrowserCaptureSession-TTO8vHtd.js">
+    <link rel="modulepreload" crossorigin href="/assets/useBrowserCaptureSession-DACautTD.js">
     <link rel="modulepreload" crossorigin href="/assets/arrow-up-right-9DoMn7fD.js">
     <link rel="modulepreload" crossorigin href="/assets/sparkles-DrY8hb0X.js">
     <link rel="modulepreload" crossorigin href="/assets/x-CBMI9ejn.js">
     <link rel="modulepreload" crossorigin href="/assets/useSharedWebSocket-DaPh7QBL.js">
-    <link rel="modulepreload" crossorigin href="/assets/useDesktop-DUvS4fuP.js">
-    <link rel="modulepreload" crossorigin href="/assets/MinimizedChatsContext-Gt6KQySM.js">
+    <link rel="modulepreload" crossorigin href="/assets/useDesktop-Cwyis9DX.js">
+    <link rel="modulepreload" crossorigin href="/assets/MinimizedChatsContext-BQQohTp2.js">
     <link rel="modulepreload" crossorigin href="/assets/external-link-BcU5EWZp.js">
     <link rel="modulepreload" crossorigin href="/assets/chevron-right-CViMxucY.js">
     <link rel="modulepreload" crossorigin href="/assets/circle-x-CMYsN4ZH.js">
@@ -274,11 +274,11 @@
     <link rel="modulepreload" crossorigin href="/assets/jira-api-BgFIr8eD.js">
     <link rel="modulepreload" crossorigin href="/assets/provider-capabilities-BvoExILy.js">
     <link rel="modulepreload" crossorigin href="/assets/lib-CGdyxIWg.js">
-    <link rel="modulepreload" crossorigin href="/assets/getTimezoneOffsetInMilliseconds-CSCbUI4W.js">
-    <link rel="modulepreload" crossorigin href="/assets/formatDistanceToNow-BjGwPf6I.js">
-    <link rel="modulepreload" crossorigin href="/assets/spending-Dq43JYmD.js">
-    <link rel="modulepreload" crossorigin href="/assets/TicketDetailModal-C-tHW-2s.js">
-    <link rel="stylesheet" crossorigin href="/assets/index-Bz0TeGRs.css">
+    <link rel="modulepreload" crossorigin href="/assets/getTimezoneOffsetInMilliseconds-B_N-0uSl.js">
+    <link rel="modulepreload" crossorigin href="/assets/formatDistanceToNow-2bGOYubE.js">
+    <link rel="modulepreload" crossorigin href="/assets/spending-B20-uFLQ.js">
+    <link rel="modulepreload" crossorigin href="/assets/TicketDetailModal-DEoAJOuD.js">
+    <link rel="stylesheet" crossorigin href="/assets/index-ChIuonbC.css">
   </head>
   <body>
     <div id="specrails-splash" aria-hidden="false" role="status" aria-label="Loading Specrails">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-desktop",
-  "version": "2.32.0",
+  "version": "2.33.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/server/dist/ai-invocations.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InvalidSurfaceError = void 0;
 exports.recordInvocation = recordInvocation;
+exports.sumInvocationCostForRuns = sumInvocationCostForRuns;
 exports.updateTicketIdForConversation = updateTicketIdForConversation;
 exports.listInvocationsForConversation = listInvocationsForConversation;
 exports.getTicketSpendingSummary = getTicketSpendingSummary;
@@ -45,6 +46,40 @@ function recordInvocation(db, input) {
     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `).run(input.id, input.project_id, input.provider, input.surface, input.surface_ref_id ?? null, input.ticket_id ?? null, input.conversation_id ?? null, input.model ?? null, input.status, input.started_at, input.finished_at ?? null, input.duration_ms ?? null, input.duration_api_ms ?? null, input.tokens_in ?? null, input.tokens_out ?? null, input.tokens_cache_read ?? null, input.tokens_cache_create ?? null, input.total_cost_usd ?? null, input.total_cost_usd_estimated ? 1 : 0, input.num_turns ?? null, input.session_id ?? null, input.loop_run_id ?? null);
 }
+/**
+ * Total AI spend attributable to a set of implementation runs, for the PR-body
+ * cost footer. A "run" id is either a loop_runs row id (loop AI-step/decider
+ * invocations link via `loop_run_id`) or a QueueManager job id (rows with
+ * surface='job' and `surface_ref_id` = the id, plus the merge-orchestrator's
+ * `<jobId>:merge:<step>` sub-rows). Failed/aborted rows count — they billed
+ * real tokens. Returns null when no priced rows match, so callers can omit
+ * the footer instead of printing $0.00 for legacy runs.
+ */
+function sumInvocationCostForRuns(db, runIds) {
+    const ids = [...new Set(runIds.filter((id) => typeof id === 'string' && id.length > 0))];
+    if (ids.length === 0)
+        return null;
+    const placeholders = ids.map(() => '?').join(', ');
+    const mergePrefixes = ids.map(() => `surface_ref_id LIKE ? ESCAPE '\\'`).join(' OR ');
+    const rows = db.prepare(`SELECT total_cost_usd, total_cost_usd_estimated FROM ai_invocations
+     WHERE total_cost_usd IS NOT NULL
+       AND (loop_run_id IN (${placeholders})
+            OR surface_ref_id IN (${placeholders})
+            OR ${mergePrefixes})`).all(...ids, ...ids, ...ids.map((id) => `${escapeLikePattern(id)}:merge:%`));
+    if (rows.length === 0)
+        return null;
+    let totalUsd = 0;
+    let estimated = false;
+    for (const row of rows) {
+        totalUsd += row.total_cost_usd;
+        if (row.total_cost_usd_estimated === 1)
+            estimated = true;
+    }
+    return { totalUsd, estimated };
+}
+function escapeLikePattern(value) {
+    return value.replace(/[\\%_]/g, (ch) => `\\${ch}`);
+}
 function updateTicketIdForConversation(db, conversationId, ticketId) {
     const result = db.prepare(`UPDATE ai_invocations SET ticket_id = ? WHERE conversation_id = ? AND ticket_id IS NULL`).run(ticketId, conversationId);
     return result.changes;

package/server/dist/job-phase-breakdown.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeJobPhaseBreakdown = computeJobPhaseBreakdown;
+const pricing_1 = require("./pricing");
+function computeJobPhaseBreakdown(events, providerId = 'claude') {
+    const phases = new Map();
+    /** tool_use id → root phase id, for transitive nested-Task attribution. */
+    const rootOf = new Map();
+    const orchestrator = emptyTotals();
+    const unattributed = emptyTotals();
+    let sawUsage = false;
+    const totalsFor = (parentId) => {
+        if (!parentId)
+            return orchestrator;
+        const rootId = rootOf.get(parentId);
+        if (!rootId)
+            return unattributed;
+        return phases.get(rootId) ?? unattributed;
+    };
+    for (const ev of events) {
+        let parsed;
+        try {
+            parsed = JSON.parse(ev.payload);
+        }
+        catch {
+            continue;
+        }
+        const parentId = typeof parsed.parent_tool_use_id === 'string' ? parsed.parent_tool_use_id : null;
+        const message = parsed.message;
+        if (parsed.type === 'assistant' && message) {
+            // Register Task spawns FIRST so a same-event usage envelope can't
+            // attribute to a phase this very event opens.
+            for (const block of contentBlocks(message)) {
+                if (block.type !== 'tool_use' || block.name !== 'Task' || typeof block.id !== 'string')
+                    continue;
+                const input = (block.input ?? {});
+                const rootId = parentId ? (rootOf.get(parentId) ?? null) : null;
+                if (rootId) {
+                    // Nested Task: its events roll up into the ancestor phase.
+                    rootOf.set(block.id, rootId);
+                }
+                else {
+                    rootOf.set(block.id, block.id);
+                    phases.set(block.id, {
+                        ...emptyTotals(),
+                        agent: typeof input.subagent_type === 'string' ? input.subagent_type : 'subagent',
+                        toolUseId: block.id,
+                        description: typeof input.description === 'string' ? input.description : null,
+                        startedAt: ev.timestamp,
+                        endedAt: null,
+                        durationMs: null,
+                    });
+                }
+            }
+            const usage = message.usage;
+            if (usage && typeof usage === 'object') {
+                sawUsage = true;
+                const target = totalsFor(parentId);
+                const tokensIn = num(usage.input_tokens);
+                const tokensOut = num(usage.output_tokens);
+                const cacheRead = num(usage.cache_read_input_tokens);
+                const cacheCreate = num(usage.cache_creation_input_tokens);
+                target.tokensIn += tokensIn;
+                target.tokensOut += tokensOut;
+                target.tokensCacheRead += cacheRead;
+                target.tokensCacheCreate += cacheCreate;
+                target.assistantEvents += 1;
+                const cost = (0, pricing_1.estimateCostUsd)(providerId, str(message.model), {
+                    tokens_in: tokensIn,
+                    tokens_out: tokensOut,
+                    tokens_cache_read: cacheRead,
+                    tokens_cache_create: cacheCreate,
+                });
+                if (cost !== null) {
+                    target.estimatedCostUsd = (target.estimatedCostUsd ?? 0) + cost;
+                }
+            }
+            continue;
+        }
+        if (parsed.type === 'user' && message) {
+            // A tool_result closing a root Task block ends that phase.
+            for (const block of contentBlocks(message)) {
+                if (block.type !== 'tool_result' || typeof block.tool_use_id !== 'string')
+                    continue;
+                const phase = phases.get(block.tool_use_id);
+                if (phase && phase.endedAt === null) {
+                    phase.endedAt = ev.timestamp;
+                    phase.durationMs = spanMs(phase.startedAt, ev.timestamp);
+                }
+            }
+        }
+    }
+    if (!sawUsage)
+        return null;
+    const hasUnattributed = unattributed.assistantEvents > 0 || unattributed.tokensIn > 0 || unattributed.tokensOut > 0;
+    return {
+        phases: [...phases.values()],
+        orchestrator,
+        unattributed: hasUnattributed ? unattributed : null,
+        estimated: true,
+    };
+}
+// ─── Internals ────────────────────────────────────────────────────────────────
+function emptyTotals() {
+    return {
+        tokensIn: 0,
+        tokensOut: 0,
+        tokensCacheRead: 0,
+        tokensCacheCreate: 0,
+        assistantEvents: 0,
+        estimatedCostUsd: null,
+    };
+}
+function contentBlocks(message) {
+    const content = message.content;
+    return Array.isArray(content) ? content : [];
+}
+function num(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+function str(value) {
+    return typeof value === 'string' ? value : null;
+}
+function spanMs(start, end) {
+    if (!start || !end)
+        return null;
+    const a = Date.parse(start);
+    const b = Date.parse(end);
+    if (Number.isNaN(a) || Number.isNaN(b) || b < a)
+        return null;
+    return b - a;
+}

package/server/dist/loop-executors.js

@@ -22,6 +22,7 @@ const spawn_lifecycle_1 = require("./spawn-lifecycle");
 const result_event_1 = require("./result-event");
 const loop_decider_1 = require("./loop-decider");
 const rail_isolation_1 = require("./rail-isolation");
+const repo_map_1 = require("./repo-map");
 const feature_flags_1 = require("./feature-flags");
 const runtime_1 = require("./providers/runtime");
 // Per-step wall-clock caps so a single hung step can't block the engine's
@@ -95,7 +96,10 @@ function runShellCommand(command, cwd, env, timeoutMs, onLine, onSpawn) {
  */
 function aiStepEnv(env, repoDir) {
     const base = repoDir ? { ...env, SPECRAILS_REPO_DIR: repoDir } : env;
-    return (0, rail_isolation_1.isRailPrDeliveryEnabled)() ? { ...base, SPECRAILS_GIT_AUTO: 'false' } : base;
+    // Deterministic repo map (zero-AI) so the pipeline's exploration phase
+    // starts oriented instead of spending its first turns on `ls`/`find`.
+    const withMap = (0, repo_map_1.injectRepoMapEnv)(base, repoDir);
+    return (0, rail_isolation_1.isRailPrDeliveryEnabled)() ? { ...withMap, SPECRAILS_GIT_AUTO: 'false' } : withMap;
 }
 /**
  * Relocated cwd is the workspace; the source repo is reached via the

package/server/dist/pr-body.js

@@ -79,8 +79,21 @@ function buildCanonicalPrBody(input) {
     const changesSection = buildChangesSection(input.changes ?? null);
     if (changesSection)
         parts.push(changesSection);
+    const costLine = buildCostFooter(input.costUsd ?? null);
+    if (costLine)
+        parts.push(costLine);
     return parts.join('\n\n');
 }
+/** `> Specrails cost: $X.XX` — the transparency footer that keeps AI spend
+ *  visible at the exact place the work is reviewed. `~` marks a total that
+ *  includes rate-card estimates (providers without native cost, kill-path
+ *  reconstructions). */
+function buildCostFooter(cost) {
+    if (!cost || !Number.isFinite(cost.totalUsd) || cost.totalUsd <= 0)
+        return null;
+    const prefix = cost.estimated ? '~' : '';
+    return `> Specrails cost: ${prefix}$${cost.totalUsd.toFixed(2)}`;
+}
 function summaryParagraph(input) {
     const n = input.tickets.length;
     const refs = input.tickets.map((t) => displayRef(t)).join(', ');

package/server/dist/project-router-jobs.js

@@ -10,6 +10,7 @@ const db_1 = require("./db");
 const queue_manager_1 = require("./queue-manager");
 const feature_flags_1 = require("./feature-flags");
 const types_1 = require("./types");
+const job_phase_breakdown_1 = require("./job-phase-breakdown");
 const providers_1 = require("./providers");
 const hooks_1 = require("./hooks");
 const explore_smash_1 = require("./explore-smash");
@@ -589,6 +590,21 @@ function registerJobsRoutes(deps) {
             res.json({ jobs });
         }
     });
+    // Per-phase cost/usage attribution, computed post-hoc from the persisted
+    // raw stream events (claude Task/parent_tool_use_id envelope). Costs are
+    // rate-card ESTIMATES and flagged as such; providers whose stream carries
+    // no per-event usage (codex/gemini/kimi) return breakdown: null.
+    router.get('/:projectId/jobs/:id/phase-breakdown', (req, res) => {
+        const { db } = ctx(req);
+        const job = db.prepare('SELECT id FROM jobs WHERE id = ?').get(req.params.id);
+        if (!job) {
+            res.status(404).json({ error: 'Job not found' });
+            return;
+        }
+        const events = db.prepare("SELECT event_type, payload, timestamp FROM events WHERE job_id = ? AND event_type IN ('assistant', 'user') ORDER BY seq ASC").all(req.params.id);
+        const breakdown = (0, job_phase_breakdown_1.computeJobPhaseBreakdown)(events);
+        res.json({ jobId: req.params.id, breakdown });
+    });
     // Must be registered BEFORE /:projectId/jobs/:id, otherwise Express matches
     // the parameterized route first with id='compare' and this never runs (the
     // Job Comparison feature would always 404).

package/server/dist/queue-manager.js

@@ -15,6 +15,7 @@ const win_spawn_1 = require("./util/win-spawn");
 const types_1 = require("./types");
 const command_resolver_1 = require("./command-resolver");
 const rail_isolation_1 = require("./rail-isolation");
+const repo_map_1 = require("./repo-map");
 const cli_prompt_1 = require("./util/cli-prompt");
 const stream_display_1 = require("./util/stream-display");
 const hooks_1 = require("./hooks");
@@ -2368,6 +2369,9 @@ class QueueManager {
         if (profileSnapshotPath) {
             spawnEnv = { ...spawnEnv, SPECRAILS_PROFILE_PATH: profileSnapshotPath };
         }
+        // Deterministic repo map (zero-AI, best-effort) — orients the pipeline's
+        // exploration phase so it doesn't spend its first turns on `ls`/`find`.
+        spawnEnv = (0, repo_map_1.injectRepoMapEnv)(spawnEnv, execution.repoDir);
         // ─── Plugin resolution + snapshot ──────────────────────────────────────
         // Active = installed + verify ok; degraded = installed but verify failed
         // or timed out. Degraded does NOT block spawn — rail proceeds, UI gets

package/server/dist/rail-pr-decision.js

@@ -73,6 +73,7 @@ const rail_pr_delivery_1 = require("./rail-pr-delivery");
 const rail_worktree_release_1 = require("./rail-worktree-release");
 const pr_naming_1 = require("./pr-naming");
 const pr_body_1 = require("./pr-body");
+const ai_invocations_1 = require("./ai-invocations");
 const jira_db_1 = require("./jira/jira-db");
 const rail_pr_store_1 = require("./rail-pr-store");
 const rail_worktrees_store_1 = require("./rail-worktrees-store");
@@ -1292,12 +1293,21 @@ async function runCreatePr(deps, row) {
     catch {
         changes = null;
     }
+    // Cost footer is best-effort: a lookup failure omits the line, never blocks.
+    let costUsd = null;
+    try {
+        costUsd = (0, ai_invocations_1.sumInvocationCostForRuns)(deps.db, snap.runIds);
+    }
+    catch {
+        costUsd = null;
+    }
     const title = (0, pr_naming_1.buildPrTitle)(ticketData, { loopName: row.loop_name });
     const body = (0, pr_body_1.buildCanonicalPrBody)({
         loopName: row.loop_name,
         baseBranch: row.base_branch,
         tickets: ticketData.map((t) => ({ ...t, branch: branchFor(t.ticketId) })),
         changes,
+        costUsd,
     });
     let next;
     // Underlying git/gh failure detail for a degraded or failed delivery —

package/server/dist/repo-map.js

@@ -0,0 +1,293 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRepoMap = buildRepoMap;
+exports.formatRepoMap = formatRepoMap;
+exports.isRepoMapEnabled = isRepoMapEnabled;
+exports.ensureRepoMapFile = ensureRepoMapFile;
+exports.injectRepoMapEnv = injectRepoMapEnv;
+exports._clearRepoMapCache = _clearRepoMapCache;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+const artifact_registry_1 = require("./artifact-registry");
+const SKIP_DIRS = new Set([
+    'node_modules', 'vendor', 'dist', 'build', 'out', 'coverage', 'target',
+    '__pycache__', 'venv', '.venv', 'Pods', 'DerivedData',
+]);
+/** Manifest filename → ecosystem label. First match wins (iteration order). */
+const MANIFESTS = [
+    ['package.json', 'node'],
+    ['pyproject.toml', 'python'],
+    ['setup.py', 'python'],
+    ['requirements.txt', 'python'],
+    ['go.mod', 'go'],
+    ['Cargo.toml', 'rust'],
+    ['pom.xml', 'jvm'],
+    ['build.gradle', 'jvm'],
+    ['build.gradle.kts', 'jvm'],
+    ['Package.swift', 'swift'],
+    ['Gemfile', 'ruby'],
+    ['composer.json', 'php'],
+];
+const MAX_SERVICES = 40;
+const README_MAX_LINES = 12;
+const README_MAX_CHARS = 800;
+/** File-count scan caps — the bucket is a rough size label, not a census. */
+const SCAN_MAX_DEPTH = 2;
+const SCAN_MAX_ENTRIES = 500;
+function buildRepoMap(repoDir) {
+    const services = [];
+    const seen = new Set();
+    const addService = (relDir) => {
+        if (seen.has(relDir) || services.length >= MAX_SERVICES + 1)
+            return;
+        const abs = relDir === '' ? repoDir : path.join(repoDir, relDir);
+        const eco = detectEcosystem(abs);
+        if (!eco)
+            return;
+        seen.add(relDir);
+        services.push({
+            dir: relDir,
+            name: packageName(abs) ?? (relDir === '' ? path.basename(repoDir) : path.basename(relDir)),
+            ecosystem: eco,
+            sizeBucket: sizeBucket(abs),
+            hasReadme: readmePath(abs) !== null,
+        });
+    };
+    addService('');
+    for (const entry of listDirs(repoDir)) {
+        addService(entry);
+    }
+    // npm/yarn workspaces can nest packages one level below the top-level scan.
+    for (const rel of resolveNpmWorkspaces(repoDir)) {
+        addService(rel);
+    }
+    const truncated = services.length > MAX_SERVICES;
+    return {
+        readmeExcerpt: readReadmeExcerpt(repoDir),
+        services: services.slice(0, MAX_SERVICES),
+        truncated,
+    };
+}
+function formatRepoMap(map) {
+    const lines = ['# Repository map (deterministic — generated by Specrails, no AI)', ''];
+    if (map.readmeExcerpt) {
+        lines.push('## README excerpt', '', map.readmeExcerpt, '');
+    }
+    lines.push('## Packages');
+    if (map.services.length === 0) {
+        lines.push('- (no recognized package manifests found)');
+    }
+    for (const s of map.services) {
+        const dirLabel = s.dir === '' ? './' : `${s.dir}/`;
+        const readme = s.hasReadme ? 'has README' : 'no README';
+        lines.push(`- \`${dirLabel}\` — ${s.name} (${s.ecosystem}, ${s.sizeBucket}, ${readme})`);
+    }
+    if (map.truncated) {
+        lines.push(`- … more packages omitted (cap ${MAX_SERVICES})`);
+    }
+    lines.push('', 'Use this map to orient exploration without spending turns on top-level discovery.', '');
+    return lines.join('\n');
+}
+const cache = new Map();
+const CACHE_TTL_MS = 60_000;
+function isRepoMapEnabled() {
+    return process.env.SPECRAILS_REPO_MAP !== 'false';
+}
+/**
+ * Build (or reuse, 60s TTL) the on-disk map for a repo/worktree. Returns the
+ * file path, or null on any failure — the map is an accelerator, never a
+ * spawn blocker.
+ */
+function ensureRepoMapFile(repoDir) {
+    try {
+        const real = fs.realpathSync(repoDir);
+        const hit = cache.get(real);
+        if (hit && Date.now() - hit.at < CACHE_TTL_MS && fs.existsSync(hit.filePath)) {
+            return hit.filePath;
+        }
+        const content = formatRepoMap(buildRepoMap(real));
+        const dir = path.join((0, artifact_registry_1.resolveHome)(), '.specrails', 'repo-maps');
+        fs.mkdirSync(dir, { recursive: true });
+        const filePath = path.join(dir, `${sha1(real)}.md`);
+        const tmp = `${filePath}.tmp-${process.pid}`;
+        fs.writeFileSync(tmp, content, 'utf8');
+        fs.renameSync(tmp, filePath);
+        cache.set(real, { filePath, at: Date.now() });
+        return filePath;
+    }
+    catch {
+        return null;
+    }
+}
+/** Add `SPECRAILS_REPO_MAP_PATH` to a spawn env. Never throws, never blocks. */
+function injectRepoMapEnv(env, repoDir) {
+    if (!repoDir || !isRepoMapEnabled())
+        return env;
+    const filePath = ensureRepoMapFile(repoDir);
+    return filePath ? { ...env, SPECRAILS_REPO_MAP_PATH: filePath } : env;
+}
+/** Test hook — clears the TTL cache. */
+function _clearRepoMapCache() {
+    cache.clear();
+}
+// ─── Internals ────────────────────────────────────────────────────────────────
+function sha1(value) {
+    return crypto.createHash('sha1').update(value).digest('hex');
+}
+function listDirs(dir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isDirectory() && !e.name.startsWith('.') && !SKIP_DIRS.has(e.name))
+        .map((e) => e.name)
+        .sort();
+}
+function detectEcosystem(dir) {
+    for (const [manifest, eco] of MANIFESTS) {
+        if (fs.existsSync(path.join(dir, manifest)))
+            return eco;
+    }
+    return null;
+}
+function packageName(dir) {
+    try {
+        const raw = fs.readFileSync(path.join(dir, 'package.json'), 'utf8');
+        const parsed = JSON.parse(raw);
+        return typeof parsed.name === 'string' && parsed.name.trim() ? parsed.name.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readmePath(dir) {
+    for (const name of ['README.md', 'readme.md', 'README.txt', 'README']) {
+        const p = path.join(dir, name);
+        if (fs.existsSync(p))
+            return p;
+    }
+    return null;
+}
+function readReadmeExcerpt(repoDir) {
+    const p = readmePath(repoDir);
+    if (!p)
+        return null;
+    try {
+        const lines = fs.readFileSync(p, 'utf8').split('\n').slice(0, README_MAX_LINES);
+        const text = lines.join('\n').trim();
+        if (!text)
+            return null;
+        return text.length > README_MAX_CHARS ? `${text.slice(0, README_MAX_CHARS)}…` : text;
+    }
+    catch {
+        return null;
+    }
+}
+/** Rough size label from a capped, shallow file count. */
+function sizeBucket(dir) {
+    let count = 0;
+    const walk = (d, depth) => {
+        if (depth > SCAN_MAX_DEPTH || count > SCAN_MAX_ENTRIES)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (count > SCAN_MAX_ENTRIES)
+                return;
+            if (e.name.startsWith('.') || SKIP_DIRS.has(e.name))
+                continue;
+            if (e.isDirectory()) {
+                walk(path.join(d, e.name), depth + 1);
+            }
+            else {
+                count++;
+            }
+        }
+    };
+    walk(dir, 0);
+    if (count < 20)
+        return 'small';
+    if (count < 150)
+        return 'medium';
+    return 'large';
+}
+/**
+ * Resolve npm/yarn `workspaces` from the root package.json. Literal paths and
+ * trailing `/*` globs only — deliberately no glob library; anything fancier
+ * falls back to the top-level scan.
+ */
+function resolveNpmWorkspaces(repoDir) {
+    let patterns = [];
+    try {
+        const raw = fs.readFileSync(path.join(repoDir, 'package.json'), 'utf8');
+        const parsed = JSON.parse(raw);
+        const ws = parsed.workspaces;
+        if (Array.isArray(ws)) {
+            patterns = ws.filter((w) => typeof w === 'string');
+        }
+        else if (ws && typeof ws === 'object' && Array.isArray(ws.packages)) {
+            patterns = (ws.packages).filter((w) => typeof w === 'string');
+        }
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const pattern of patterns) {
+        const clean = pattern.replace(/^\.\//, '');
+        if (clean.endsWith('/*')) {
+            const base = clean.slice(0, -2);
+            const abs = path.join(repoDir, base);
+            for (const child of listDirs(abs)) {
+                out.push(path.join(base, child));
+            }
+        }
+        else if (!clean.includes('*')) {
+            out.push(clean);
+        }
+    }
+    return out;
+}