specrails-desktop 2.64.2 → 2.65.0

package/server/dist/modules/specs/runtime/triage.js

@@ -0,0 +1,365 @@
+"use strict";
+// Spec triage — effectful coordinator (launch-triage, feedback-2026-10 annex D.2).
+//
+// Deterministic inputs first (ticket text, repo map, files touched by similar
+// tickets via file_provenance, available loops), hashed;
+// then ONE cheap structured-output call on the triage engine. The record lands
+// in `metadata.triage` of the ticket store and is announced as `ticket_updated`.
+//
+// Triggers: one per-project service observes the project's ticket broadcasts
+// and schedules a debounced scan; only draft/todo specs whose content changed
+// since the project opened are triaged automatically. `triageNow` serves the
+// on-demand "Recalculate" (forced). One triage runs at a time per project.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpecTriageService = exports.TRIAGE_DEBOUNCE_MS = void 0;
+exports.cheapestModelForProvider = cheapestModelForProvider;
+exports.resolveTriageEngine = resolveTriageEngine;
+exports.hashTriageInputs = hashTriageInputs;
+exports.listTriageLoops = listTriageLoops;
+exports.triageApplicability = triageApplicability;
+const crypto_1 = require("crypto");
+const providers_1 = require("../../../providers");
+const runtime_1 = require("../../../providers/runtime");
+const provider_selection_1 = require("../../../provider-selection");
+const repo_map_1 = require("../../../repo-map");
+const feature_flags_1 = require("../../../feature-flags");
+const ai_invocations_1 = require("../../accounting/runtime/ai-invocations");
+const pricing_1 = require("../../accounting/runtime/pricing");
+const loop_role_engines_1 = require("../../loops/runtime/loop-role-engines");
+const loop_factory_1 = require("../../loops/runtime/loop-factory");
+const loops_store_1 = require("../../loops/runtime/loops-store");
+const loop_graph_1 = require("../../loops/runtime/loop-graph");
+const spec_models_1 = require("./spec-models");
+const ticket_store_1 = require("./ticket-store");
+const triage_1 = require("../domain/triage");
+const triage_runner_1 = require("./triage-runner");
+exports.TRIAGE_DEBOUNCE_MS = 2_000;
+const REPO_MAP_TTL_MS = 60_000;
+const AUTO_STATUSES = new Set(['draft', 'todo']);
+/**
+ * Cheapest catalog model of a provider by the local pricing table (input-weighted:
+ * a triage reads ~20× more than it writes). Unpriced catalogs (local engines)
+ * fall back to the provider default.
+ */
+function cheapestModelForProvider(provider) {
+    let best = null;
+    for (const option of (0, spec_models_1.getModelsForProvider)(provider)) {
+        const price = (0, pricing_1.resolvePriceEntry)(provider, option.value);
+        if (!price)
+            continue;
+        const score = price.inputPer1M + price.outputPer1M / 20;
+        if (!best || score < best.score)
+            best = { model: option.value, score };
+    }
+    return best?.model ?? (0, spec_models_1.getProviderDefault)(provider);
+}
+/** The `triage` role engine when configured and usable, else the primary provider's cheapest model. */
+function resolveTriageEngine(project) {
+    const stored = (0, loop_role_engines_1.loadLoopRoleEngines)(project).triage;
+    let provider = (0, provider_selection_1.derivePrimaryProvider)(project);
+    let model;
+    if (stored && (0, provider_selection_1.isProviderEnabled)(project, stored.provider) && (0, providers_1.hasAdapter)(stored.provider)) {
+        provider = stored.provider;
+        model = stored.model && (0, spec_models_1.isValidModelForProvider)(stored.model, provider) ? stored.model : undefined;
+    }
+    if (!(0, provider_selection_1.isProviderEnabled)(project, provider))
+        return { ok: false, reason: `provider_not_detected:${provider}` };
+    if (!(0, providers_1.hasAdapter)(provider))
+        return { ok: false, reason: `provider_not_registered:${provider}` };
+    if (!(0, runtime_1.pureOutputToolPolicy)((0, providers_1.getAdapter)(provider)))
+        return { ok: false, reason: `provider_tool_policy_unsupported:${provider}` };
+    const resolved = model ?? cheapestModelForProvider(provider);
+    if (!resolved)
+        return { ok: false, reason: `no_model:${provider}` };
+    return { ok: true, engine: { provider, model: resolved } };
+}
+// ─── Inputs ───────────────────────────────────────────────────────────────────
+function hashTriageInputs(inputs) {
+    return 'sha256:' + (0, crypto_1.createHash)('sha256').update((0, triage_1.canonicalJson)(inputs), 'utf8').digest('hex');
+}
+/** Loops a triage may recommend: the rail built-ins the primary engine can run, plus published spec-driven custom loops. */
+function listTriageLoops(db, primaryProvider) {
+    const loopsOn = (0, feature_flags_1.isLoopsEnabled)();
+    const freestyle = (0, providers_1.hasAdapter)(primaryProvider) && (0, providers_1.getAdapter)(primaryProvider).capabilities.freestyle === true;
+    const out = loop_factory_1.FACTORY_LOOPS
+        .filter((f) => (f.id !== 'factory:freestyle' || freestyle) && (f.id !== 'factory:sdd-quick-openspec' || loopsOn))
+        .map((f) => ({ id: f.id, name: f.name, description: f.description.slice(0, 240) }));
+    if (loopsOn) {
+        try {
+            for (const loop of (0, loops_store_1.listLoops)(db)) {
+                if (loop.builtinId || loop.status !== 'published' || !(0, loop_graph_1.loopNeedsTicket)(loop.graph))
+                    continue;
+                out.push({ id: loop.id, name: loop.name.slice(0, 80), description: (loop.description ?? '').slice(0, 240) });
+            }
+        }
+        catch { /* loops table unavailable: built-ins only */ }
+    }
+    return out;
+}
+function filesTouchedByTickets(db, ticketIds) {
+    if (ticketIds.length === 0)
+        return [];
+    try {
+        const rows = db.prepare(`SELECT file_path FROM file_provenance WHERE ticket_id IN (${ticketIds.map(() => '?').join(',')}) AND kind != 'deleted'`).all(...ticketIds);
+        return (0, triage_1.rankFiles)(rows.map((r) => r.file_path));
+    }
+    catch {
+        return [];
+    }
+}
+function toTriageRepoMap(projectPath) {
+    try {
+        const map = (0, repo_map_1.buildRepoMap)(projectPath);
+        return {
+            readmeExcerpt: map.readmeExcerpt ? map.readmeExcerpt.slice(0, triage_1.TRIAGE_LIMITS.readme) : null,
+            services: map.services.map(({ dir, name, ecosystem, sizeBucket }) => ({ dir, name, ecosystem, sizeBucket })),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Specs a trigger may consider at all (on demand or automatically). */
+function triageApplicability(ticket) {
+    if (ticket.status === 'cancelled')
+        return 'cancelled';
+    if (ticket.is_epic)
+        return 'epic';
+    if ((0, ticket_store_1.isFlowHeldTicket)(ticket))
+        return 'flow';
+    return 'ok';
+}
+class SpecTriageService {
+    deps;
+    seen = new Map();
+    pending = new Set();
+    chain = Promise.resolve();
+    timer = null;
+    abort = new AbortController();
+    disposed = false;
+    repoMapCache = null;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Seed the content signatures: specs present at startup are not auto-triaged. */
+    start() {
+        try {
+            for (const ticket of Object.values((0, ticket_store_1.readStore)(this.deps.ticketsPath()).tickets)) {
+                this.seen.set(ticket.id, (0, triage_1.triageContentSignature)(ticket));
+            }
+        }
+        catch { /* no store yet: every later spec is new */ }
+    }
+    /** Broadcast tap: any ticket message schedules one debounced scan. */
+    observe(msg) {
+        if (this.disposed)
+            return;
+        if (msg.type !== 'ticket_created' && msg.type !== 'ticket_updated')
+            return;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = setTimeout(() => { this.timer = null; this.scan(); }, this.deps.debounceMs ?? exports.TRIAGE_DEBOUNCE_MS);
+        if (typeof this.timer.unref === 'function')
+            this.timer.unref();
+    }
+    /** Compare signatures and queue the specs created or edited since last seen. */
+    scan() {
+        if (this.disposed || !(this.deps.autoEnabled ?? feature_flags_1.isSpecTriageAutoEnabled)())
+            return;
+        let store;
+        try {
+            store = (0, ticket_store_1.readStore)(this.deps.ticketsPath());
+        }
+        catch {
+            return;
+        }
+        for (const ticket of Object.values(store.tickets)) {
+            const signature = (0, triage_1.triageContentSignature)(ticket);
+            const previous = this.seen.get(ticket.id);
+            this.seen.set(ticket.id, signature);
+            if (previous === signature)
+                continue;
+            if (!AUTO_STATUSES.has(ticket.status) || triageApplicability(ticket) !== 'ok')
+                continue;
+            this.enqueue(ticket.id, false);
+        }
+    }
+    /** On-demand triage. `force` ignores an unchanged inputsHash (Recalculate). */
+    triageNow(ticketId, opts = {}) {
+        return this.enqueue(ticketId, opts.force === true);
+    }
+    dispose() {
+        this.disposed = true;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.abort.abort();
+    }
+    enqueue(ticketId, force) {
+        if (!force) {
+            if (this.pending.has(ticketId))
+                return Promise.resolve({ kind: 'queued' });
+            this.pending.add(ticketId);
+        }
+        const run = this.chain.then(async () => {
+            this.pending.delete(ticketId);
+            if (this.disposed)
+                return { kind: 'disposed' };
+            return this.run(ticketId, force);
+        });
+        this.chain = run.catch((err) => { console.error(`[triage] spec #${ticketId} failed:`, err); });
+        return run;
+    }
+    repoMap() {
+        if (this.deps.repoMap)
+            return this.deps.repoMap();
+        const now = Date.now();
+        if (!this.repoMapCache || now - this.repoMapCache.at > REPO_MAP_TTL_MS) {
+            this.repoMapCache = { at: now, value: toTriageRepoMap(this.deps.project.path) };
+        }
+        return this.repoMapCache.value;
+    }
+    async collectInputs(ticket, store, engine) {
+        const others = Object.values(store.tickets).filter((t) => !t.is_epic);
+        const similar = (0, triage_1.similarTicketIds)({ id: ticket.id, title: ticket.title, labels: ticket.labels ?? [] }, others.map((t) => ({ id: t.id, title: t.title, labels: t.labels ?? [] })));
+        const loops = this.deps.loops?.() ?? listTriageLoops(this.deps.db, (0, provider_selection_1.derivePrimaryProvider)(this.deps.project));
+        const inputs = {
+            promptVersion: triage_1.TRIAGE_PROMPT_VERSION,
+            ticket: (0, triage_1.triageTicketText)(ticket),
+            repoMap: this.repoMap(),
+            similarFiles: filesTouchedByTickets(this.deps.db, similar),
+            loops: loops.map(({ id, name, description }) => ({ id, name, description })),
+            engine: engine.ok ? `${engine.engine.provider}:${engine.engine.model}` : null,
+        };
+        return { inputs, loops };
+    }
+    async run(ticketId, force) {
+        let store;
+        try {
+            store = (0, ticket_store_1.readStore)(this.deps.ticketsPath());
+        }
+        catch {
+            return { kind: 'not_found' };
+        }
+        const ticket = store.tickets[String(ticketId)];
+        if (!ticket)
+            return { kind: 'not_found' };
+        const applicability = triageApplicability(ticket);
+        if (applicability !== 'ok')
+            return { kind: 'not_applicable', reason: applicability };
+        const engine = (this.deps.resolveEngine ?? (() => resolveTriageEngine(this.deps.project)))();
+        const { inputs, loops } = await this.collectInputs(ticket, store, engine);
+        const inputsHash = hashTriageInputs(inputs);
+        const existing = ticket.metadata?.triage;
+        if (!force && (0, triage_1.isTicketTriage)(existing) && existing.inputsHash === inputsHash)
+            return { kind: 'unchanged', triage: existing };
+        const computedAt = () => (this.deps.now?.() ?? new Date()).toISOString();
+        let record;
+        if (!engine.ok) {
+            record = { status: 'unavailable', reason: engine.reason, inputsHash, computedAt: computedAt() };
+        }
+        else {
+            record = await this.callModel(ticket.id, engine.engine, inputs, loops, inputsHash, computedAt);
+        }
+        if (this.disposed)
+            return { kind: 'disposed' };
+        const written = this.write(ticket.id, record);
+        return written ? { kind: 'stored', triage: record } : { kind: 'not_found' };
+    }
+    async callModel(ticketId, engine, inputs, loops, inputsHash, computedAt) {
+        const startedAt = computedAt();
+        const runModel = this.deps.runModel ?? triage_runner_1.runTriageModel;
+        let usage;
+        let record;
+        let status = 'success';
+        try {
+            const result = await runModel({
+                projectId: this.deps.project.id,
+                project: this.deps.project,
+                provider: engine.provider,
+                model: engine.model,
+                systemPrompt: (0, triage_1.buildTriageSystemPrompt)(),
+                userPrompt: (0, triage_1.buildTriageUserPrompt)(inputs),
+                signal: this.abort.signal,
+            });
+            usage = result;
+            const parsed = (0, triage_1.parseTriageOutput)(result.text, { loops });
+            if (parsed.ok) {
+                record = { status: 'ready', ...parsed.value, inputsHash, model: result.model, costUsd: result.costUsd, computedAt: computedAt() };
+            }
+            else {
+                status = 'failed';
+                record = { status: 'failed', error: `invalid_output:${parsed.error}`, inputsHash, model: result.model, costUsd: result.costUsd, computedAt: computedAt() };
+            }
+        }
+        catch (err) {
+            usage = err instanceof triage_runner_1.TriageModelError ? err.partial : undefined;
+            status = this.abort.signal.aborted ? 'aborted' : 'failed';
+            record = {
+                status: 'failed',
+                error: (err instanceof Error ? err.message : String(err)).slice(0, 300),
+                inputsHash,
+                model: usage?.model ?? engine.model,
+                costUsd: usage?.costUsd ?? null,
+                computedAt: computedAt(),
+            };
+        }
+        try {
+            (0, ai_invocations_1.recordInvocation)(this.deps.db, {
+                id: (0, crypto_1.randomUUID)(),
+                project_id: this.deps.project.id,
+                provider: usage?.provider ?? engine.provider,
+                surface: 'triage',
+                surface_ref_id: null,
+                ticket_id: ticketId,
+                status,
+                started_at: startedAt,
+                finished_at: computedAt(),
+                model: usage?.model ?? engine.model,
+                total_cost_usd: usage?.costUsd ?? undefined,
+                total_cost_usd_estimated: usage?.costEstimated === true,
+                tokens_in: usage?.tokensIn ?? undefined,
+                tokens_out: usage?.tokensOut ?? undefined,
+                tokens_cache_read: usage?.tokensCacheRead,
+                tokens_cache_create: usage?.tokensCacheCreate,
+                duration_ms: usage?.durationMs,
+                num_turns: 1,
+            });
+        }
+        catch (err) {
+            console.error('[triage] recordInvocation failed:', err);
+        }
+        return record;
+    }
+    /** Persist without touching `updated_at` (triage is not a user edit). */
+    write(ticketId, record) {
+        let saved;
+        let revision = 0;
+        try {
+            const store = (0, ticket_store_1.mutateStore)(this.deps.ticketsPath(), (s) => {
+                const ticket = s.tickets[String(ticketId)];
+                if (!ticket)
+                    return;
+                ticket.metadata = { ...(ticket.metadata ?? {}), triage: record };
+                saved = ticket;
+            });
+            revision = store.revision;
+        }
+        catch (err) {
+            console.error(`[triage] write for spec #${ticketId} failed:`, err);
+            return false;
+        }
+        if (!saved)
+            return false;
+        this.deps.notifyDesktopWrite?.(revision);
+        this.deps.broadcast({
+            type: 'ticket_updated',
+            ticket: saved,
+            projectId: this.deps.project.id,
+            timestamp: (this.deps.now?.() ?? new Date()).toISOString(),
+        });
+        return true;
+    }
+}
+exports.SpecTriageService = SpecTriageService;

package/server/dist/modules/terminals/domain/app-urls.js

@@ -0,0 +1,96 @@
+"use strict";
+// Pure rules for the addresses a background process (a dev server) announces in
+// its output: where it can be opened on this machine (`local`) and from another
+// device on the same network (`network`). No I/O — the runtime feeds log lines
+// and this machine's LAN addresses in.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPrivateIPv4 = isPrivateIPv4;
+exports.appUrlsFromLines = appUrlsFromLines;
+const ANSI = /\u001b\[[0-?]*[ -/]*[@-~]|\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)|\u001b[@-Z\\-_]/g;
+// Host (bracketed IPv6 or plain, port included), then an optional path.
+const URL_IN_TEXT = /\bhttps?:\/\/(?:\[[0-9a-f:.]+\]|[^\s'"<>()[\]`/]+)(?::\d+)?(?:\/[^\s'"<>)\]`]*)?/gi;
+const TRAILING_PUNCTUATION = /[.,;:!?]+$/;
+const MAX_URLS = 4;
+function ipv4(host) {
+    const parts = host.split('.');
+    if (parts.length !== 4)
+        return null;
+    const octets = parts.map((part) => (/^\d{1,3}$/.test(part) ? Number(part) : NaN));
+    return octets.every((octet) => octet <= 255) ? octets : null;
+}
+/**
+ * Whether `address` is reachable only from a private network: RFC 1918, or the
+ * 100.64/10 shared range that Tailscale-style VPNs use. Public and link-local
+ * addresses are excluded.
+ */
+function isPrivateIPv4(address) {
+    const o = ipv4(address);
+    if (!o)
+        return false;
+    return o[0] === 10 || (o[0] === 172 && o[1] >= 16 && o[1] <= 31) || (o[0] === 192 && o[1] === 168) ||
+        (o[0] === 100 && o[1] >= 64 && o[1] <= 127);
+}
+function hostKind(hostname) {
+    const host = hostname.toLowerCase().replace(/^\[/, '').replace(/\]$/, '');
+    if (host === 'localhost' || host.endsWith('.localhost') || host === '::1' || /^127(?:\.\d{1,3}){3}$/.test(host))
+        return 'local';
+    if (host === '0.0.0.0' || host === '::')
+        return 'wildcard';
+    if (isPrivateIPv4(host) || host.endsWith('.local'))
+        return 'network';
+    return 'other';
+}
+/** Parse an announced URL; only explicit ports count (bare hosts are usually docs). */
+function parseAnnounced(raw) {
+    let url;
+    try {
+        url = new URL(raw.replace(TRAILING_PUNCTUATION, ''));
+    }
+    catch {
+        return null;
+    }
+    const port = Number(url.port);
+    if (!url.port || !Number.isInteger(port) || port < 1 || port > 65535)
+        return null;
+    url.hash = '';
+    return url;
+}
+/**
+ * The app URLs announced by a process's log lines (oldest first). Each list is
+ * latest-first and unique per origin, so a restarted server's new address wins.
+ * A wildcard bind (`http://0.0.0.0:3000`) is reachable both locally and on every
+ * LAN address of this machine.
+ */
+function appUrlsFromLines(lines, lanAddresses) {
+    const local = new Map();
+    const network = new Map();
+    const add = (into, url) => {
+        into.delete(url.origin);
+        into.set(url.origin, url.toString());
+    };
+    for (const line of lines) {
+        for (const match of line.replace(ANSI, '').matchAll(URL_IN_TEXT)) {
+            const url = parseAnnounced(match[0]);
+            if (!url)
+                continue;
+            const kind = hostKind(url.hostname);
+            if (kind === 'local') {
+                url.hostname = 'localhost';
+                add(local, url);
+            }
+            else if (kind === 'network') {
+                add(network, url);
+            }
+            else if (kind === 'wildcard') {
+                url.hostname = 'localhost';
+                add(local, url);
+                for (const address of lanAddresses) {
+                    url.hostname = address;
+                    add(network, url);
+                }
+            }
+        }
+    }
+    const latest = (urls) => [...urls.values()].reverse().slice(0, MAX_URLS);
+    return { local: latest(local), network: latest(network) };
+}

package/server/dist/modules/terminals/runtime/app-urls.js

@@ -0,0 +1,77 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withAppUrls = void 0;
+exports.lanIPv4Addresses = lanIPv4Addresses;
+exports.createAppUrlResolver = createAppUrlResolver;
+const node_os_1 = __importDefault(require("node:os"));
+const transient_children_1 = require("../../../transient-children");
+const app_urls_1 = require("../domain/app-urls");
+/** Statuses whose announced URLs are still served. */
+const LIVE_STATUSES = new Set(['starting', 'running']);
+/** Dev servers announce their URL early but may re-announce after a restart. */
+const SCAN_LIMIT = 2000;
+const MAX_MEMO_ENTRIES = 256;
+/** This machine's private IPv4 addresses (Wi-Fi/Ethernet and VPNs such as Tailscale). */
+function lanIPv4Addresses() {
+    const addresses = [];
+    for (const entries of Object.values(node_os_1.default.networkInterfaces())) {
+        for (const entry of entries ?? []) {
+            if (entry.family === 'IPv4' && !entry.internal && (0, app_urls_1.isPrivateIPv4)(entry.address))
+                addresses.push(entry.address);
+        }
+    }
+    return addresses;
+}
+const defaultDeps = {
+    logs: (process) => (0, transient_children_1.getBackgroundProcessLogs)(process.pid, { projectId: process.projectId, processId: process.processId, limit: SCAN_LIMIT }),
+    lanAddresses: lanIPv4Addresses,
+};
+/**
+ * Attaches `appUrls` to a running process: the addresses its own output
+ * announced, so Desktop and the Companion can offer them as links that open in
+ * the device's browser. Derived on read and never persisted; finished or
+ * recovered processes get none. A memo keyed on the log tail keeps repeated
+ * reads cheap.
+ */
+function createAppUrlResolver(deps = defaultDeps) {
+    const memo = new Map();
+    return (process) => {
+        if (!LIVE_STATUSES.has(process.status)) {
+            memo.delete(process.processId);
+            return process;
+        }
+        let snapshot = null;
+        try {
+            snapshot = deps.logs(process);
+        }
+        catch {
+            snapshot = null;
+        }
+        if (!snapshot)
+            return process;
+        let lan = [];
+        try {
+            lan = deps.lanAddresses();
+        }
+        catch {
+            lan = [];
+        }
+        const last = snapshot.lines[snapshot.lines.length - 1];
+        const key = `${snapshot.nextSequence}:${last?.sequence ?? 0}:${last?.line.length ?? 0}:${lan.join(',')}`;
+        let entry = memo.get(process.processId);
+        if (entry?.key !== key) {
+            // Keyed by unique execution id; bound it for processes never read again after exiting.
+            if (!entry && memo.size >= MAX_MEMO_ENTRIES)
+                memo.clear();
+            entry = { key, urls: (0, app_urls_1.appUrlsFromLines)(snapshot.lines.map((line) => line.line), lan) };
+            memo.set(process.processId, entry);
+        }
+        const { local, network } = entry.urls;
+        return local.length || network.length ? { ...process, appUrls: { local: [...local], network: [...network] } } : process;
+    };
+}
+/** Shared resolver for routes, events and the mission MCP tools. */
+exports.withAppUrls = createAppUrlResolver();

package/server/dist/modules/terminals/runtime/background-process-service.js

@@ -12,43 +12,40 @@ const node_path_1 = __importDefault(require("node:path"));
 const loop_runs_store_1 = require("../../loops/runtime/loop-runs-store");
 const project_repositories_1 = require("../../../project-repositories");
 const transient_children_1 = require("../../../transient-children");
-const preview_origins_1 = require("../../browser/domain/preview-origins");
-/** The same scope and lifecycle policy applies to REST and the mission MCP. */
-function resolveBackgroundCwd(repositoryRoot, cwd) {
+const app_urls_1 = require("./app-urls");
+/** The same scope and lifecycle policy applies to REST and the mission MCP.
+ * `scope` names the root in the refusal (a repository, or a Flow worktree). */
+function resolveBackgroundCwd(repositoryRoot, cwd, scope = 'the selected repository') {
     if (cwd !== undefined && typeof cwd !== 'string')
         throw new project_repositories_1.RepositoryValidationError('cwd must be a string');
     const resolved = node_path_1.default.resolve(repositoryRoot, typeof cwd === 'string' && cwd.trim() ? cwd : '.');
     if (!(0, project_repositories_1.isRepositoryPathWithin)((0, project_repositories_1.canonicalRepositoryPath)(repositoryRoot), (0, project_repositories_1.canonicalRepositoryPath)(resolved))) {
-        throw new project_repositories_1.RepositoryValidationError('background_start cwd must stay within the selected repository.');
+        throw new project_repositories_1.RepositoryValidationError(`background_start cwd must stay within ${scope}.`);
     }
     return resolved;
 }
-function backgroundProcessHooks(broadcast) {
-    const publish = (type) => (process) => broadcast({ type, process,
-        projectId: process.projectId, timestamp: new Date().toISOString() });
-    // Companion app preview: announce once per newly seen local origin so phones
-    // refetch the derived targets instead of tailing every log line.
-    const announced = new Set();
-    const onOutput = (event) => {
-        let fresh = false;
-        for (const url of (0, preview_origins_1.extractPreviewUrls)(event.line)) {
-            const origin = (0, preview_origins_1.previewOrigin)(url);
-            if (origin && !announced.has(origin)) {
-                announced.add(origin);
-                fresh = true;
-            }
-        }
-        if (fresh)
-            broadcast({ type: 'background_process.preview_targets', processId: event.processId, chatId: event.chatId,
-                projectId: event.projectId, timestamp: new Date().toISOString() });
+function backgroundProcessHooks(broadcast, resolveAppUrls = app_urls_1.withAppUrls) {
+    // Every event carries the current app URLs so clients can replace their
+    // snapshot wholesale without losing the links.
+    let announced = '';
+    const send = (type, process) => {
+        const resolved = resolveAppUrls(process);
+        announced = JSON.stringify(resolved.appUrls ?? null);
+        broadcast({ type, process: resolved, projectId: process.projectId, timestamp: new Date().toISOString() });
     };
-    const exited = publish('background_process.exited');
-    return {
-        onStarted: publish('background_process.started'),
-        onUpdated: publish('background_process.updated'),
-        onOutput,
-        onExited: (process) => { announced.clear(); exited(process); },
+    const publish = (type) => (process) => send(type, process);
+    // A dev server prints its address once it is listening: announce new or
+    // changed addresses as an update instead of making clients tail the logs.
+    const onOutput = (event) => {
+        if (!/https?:\/\//i.test(event.line))
+            return;
+        const process = (0, transient_children_1.getBackgroundProcess)(event.pid, event.processId);
+        if (!process || process.projectId !== event.projectId)
+            return;
+        if (JSON.stringify(resolveAppUrls(process).appUrls ?? null) !== announced)
+            send('background_process.updated', process);
     };
+    return { onStarted: publish('background_process.started'), onUpdated: publish('background_process.updated'), onOutput, onExited: publish('background_process.exited') };
 }
 function backgroundStartBusyReason(c) {
     const activeJobId = typeof c.queueManager?.getActiveJobId === 'function' ? c.queueManager.getActiveJobId() : null;