@repo-os/repoos 0.5.45

package/dist/server/ntfy.js

@@ -0,0 +1,112 @@
+const NTFY_DEFAULT_BASE_URL = "https://ntfy.sh";
+/** The ntfy server base URL: env var wins, then config, then the default. */
+export function ntfyBaseUrl(config) {
+    const fromEnv = process.env.NTFY_BASE_URL?.trim();
+    return (fromEnv || config.ntfyBaseUrl || NTFY_DEFAULT_BASE_URL).replace(/\/+$/, "");
+}
+/** Truncate title to fit on one line with the headline. Aim for ~50 chars total. */
+function truncateTitle(title, headlineLen) {
+    const maxLen = 50 - headlineLen - 3; // 3 for " · "
+    if (title.length <= maxLen)
+        return title;
+    return title.slice(0, Math.max(1, maxLen - 1)) + "…";
+}
+/**
+ * Build a notification spec for a status transition, or null if no notification applies.
+ * For ready → active, returns "Started" (lower priority to avoid noise).
+ * For active/review → done, returns "Done" (lower priority).
+ * Other transitions do not currently trigger notifications.
+ */
+export function notificationForStatusChange(prev, next) {
+    if (prev === "ready" && next === "active") {
+        return { headline: "▶️ Started", priority: "low" };
+    }
+    if ((prev === "active" || prev === "review") && next === "done") {
+        return { headline: "✅ Done", priority: "low" };
+    }
+    return null;
+}
+/**
+ * Build a notification spec for task creation.
+ * Returns "New" with low priority (informational).
+ */
+export function notificationForTaskCreated() {
+    return { headline: "🆕 New", priority: "low" };
+}
+/**
+ * Build a notification spec when a task needs human input.
+ * Returns "Needs you" with high priority and a subtitle explaining the situation.
+ */
+export function notificationForNeedsInput() {
+    return {
+        headline: "🙋 Needs you",
+        priority: "high",
+        subtitle: "Agent is waiting for your decision",
+    };
+}
+/** Format a notification spec into the final message string. */
+export function formatNotification(spec, title) {
+    const truncated = truncateTitle(title, spec.headline.length);
+    const message = `${spec.headline} · ${truncated}`;
+    if (spec.subtitle) {
+        return `${message}\n${spec.subtitle}`;
+    }
+    return message;
+}
+/** True when notifications are enabled AND a topic is configured. */
+export function shouldSend(config) {
+    if (config.ntfyEnabled !== true) {
+        console.log(`[ntfy] Notifications disabled (ntfyEnabled=${config.ntfyEnabled})`);
+        return false;
+    }
+    const topic = (config.ntfyTopic ?? "").trim();
+    if (topic.length === 0) {
+        console.log(`[ntfy] No topic configured (ntfyTopic="${config.ntfyTopic}")`);
+        return false;
+    }
+    console.log(`[ntfy] Notifications enabled for topic: ${topic}`);
+    return true;
+}
+/** Best-effort publish of a message to the configured topic. Never throws. */
+export function publish(config, message, priority = "default") {
+    if (!shouldSend(config))
+        return;
+    const topic = encodeURIComponent((config.ntfyTopic ?? "").trim());
+    const url = `${ntfyBaseUrl(config)}/${topic}`;
+    void fetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "text/plain",
+            Title: "RepoOS",
+            Priority: priority,
+        },
+        body: message,
+    }).catch((err) => {
+        // Log errors for debugging, but never throw
+        console.error(`[ntfy] Failed to send notification to ${url}:`, err);
+    });
+}
+/** Fire a notification for a task status transition, if one applies. */
+export function notifyStatusChange(config, task, prev, next) {
+    const spec = notificationForStatusChange(prev, next);
+    if (spec) {
+        const message = formatNotification(spec, task.title);
+        console.log(`[ntfy] Sending notification for ${task.id}: ${prev} → ${next}`);
+        publish(config, message, spec.priority);
+    }
+    else {
+        console.log(`[ntfy] No notification for ${task.id}: ${prev} → ${next} (no message configured)`);
+    }
+}
+/** Fire a notification when a task is created (stretch from #0134). */
+export function notifyTaskCreated(config, task) {
+    const spec = notificationForTaskCreated();
+    const message = formatNotification(spec, task.title);
+    publish(config, message, spec.priority);
+}
+/** Fire a notification when a task needs human input. */
+export function notifyNeedsInput(config, task) {
+    const spec = notificationForNeedsInput();
+    const message = formatNotification(spec, task.title);
+    publish(config, message, spec.priority);
+}

package/dist/server/pm-attachments.d.ts

@@ -0,0 +1,35 @@
+import type { RepoOSConfig, Task } from "../core/types.js";
+export interface QueuedPmImages {
+    batchId: string | null;
+    /** How many images actually landed in the pending batch. */
+    queued: number;
+    /** Per-image rejection reasons (bad type, empty, too large). */
+    errors: string[];
+}
+/** The shape the client posts per image (same as the attachment-upload endpoint). */
+export interface IncomingPmImage {
+    name?: unknown;
+    mime?: unknown;
+    data?: unknown;
+}
+/**
+ * Validate and park images from one PM chat message as a pending batch keyed
+ * to that session. Never throws — per-image problems come back as `errors`
+ * while the rest of the batch still queues.
+ */
+export declare function queuePmImages(config: RepoOSConfig, sessionKey: string, images: IncomingPmImage[]): QueuedPmImages;
+/** Remove a just-queued batch (e.g. the PM send was rejected) and its files. */
+export declare function dropPmImages(batchId: string | null): void;
+/**
+ * Attach the oldest pending batch whose PM session is still running to a
+ * freshly created task: move the files into the task's attachment folder
+ * under the usual `screenshot-N` names, reference them from the task body's
+ * `## Screenshots` section, and return the re-parsed task for the caller to
+ * apply to the index. Returns null when nothing is pending for a running
+ * session — the common case — or on any failure (best-effort; a failed
+ * attach never blocks the task creation itself, and the batch is dropped so
+ * a half-attached set cannot re-attach to a later task).
+ */
+export declare function attachPendingPmImages(config: RepoOSConfig, task: Task, isSessionRunning: (sessionKey: string) => boolean): Task | null;
+/** Test hook: drop all in-memory batches (files under tmp roots are removed by the tests). */
+export declare function resetPmImages(): void;

package/dist/server/pm-attachments.js

@@ -0,0 +1,181 @@
+/**
+ * Chat-input screenshots carried onto the task the PM creates from them (0381).
+ *
+ * When a PM chat message arrives with images, the task it will spawn does not
+ * exist yet — the PM authors it later, mid-run, through `repoos new`. So the
+ * message route cannot attach the images the way the New-task panel does
+ * (there the task id is known at upload time). Instead the images are parked
+ * on disk as a pending batch keyed to the PM session, and the moment a task
+ * is created while that session is running, the batch is moved into the new
+ * task's attachment folder and referenced from its `## Screenshots` section —
+ * the exact storage/serving convention every other screenshot uses
+ * (`work/.attachments/<taskId>/`, gitignored, served from disk).
+ *
+ * Matching rule: the oldest pending batch whose PM session is still running
+ * wins. Runs are short and a user attaches images seconds before the PM
+ * starts working, so "created while that session is running" almost always
+ * means "created from this message"; a human creating a task inside that
+ * same window is the rare false positive, bounded by a 10-minute TTL.
+ * Unclaimed batches (the PM never creates a task) expire and are deleted —
+ * the pending folder never accumulates.
+ */
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { MAX_SCREENSHOT_BYTES, SCREENSHOT_MIME, attachmentsDir, sanitizeName, screenshotUrl, } from "./attachments.js";
+import { patchTaskFile } from "./write.js";
+const batches = new Map();
+/** A batch unclaimed this long is deleted — the PM run that would claim it is long over. */
+const PENDING_TTL_MS = 10 * 60 * 1000;
+/** Upper bound on queued batches per PM session (each send with images = one batch). */
+const MAX_BATCHES_PER_SESSION = 8;
+/** Pending storage lives beside the task attachment folders, under the gitignored work dir. */
+function pendingRoot(config) {
+    return join(config.root, config.workDir, ".attachments", "_pm-pending");
+}
+/** Delete every batch past its TTL, and its files. Runs on every entry point. */
+function prune() {
+    const now = Date.now();
+    for (const [id, batch] of batches) {
+        if (now - batch.at <= PENDING_TTL_MS)
+            continue;
+        batches.delete(id);
+        rmSync(batch.dir, { recursive: true, force: true });
+    }
+}
+/**
+ * Validate and park images from one PM chat message as a pending batch keyed
+ * to that session. Never throws — per-image problems come back as `errors`
+ * while the rest of the batch still queues.
+ */
+export function queuePmImages(config, sessionKey, images) {
+    prune();
+    const errors = [];
+    if (!Array.isArray(images) || images.length === 0) {
+        return { batchId: null, queued: 0, errors };
+    }
+    const dir = join(pendingRoot(config), `${Date.now()}-${randomUUID().slice(0, 8)}`);
+    const saved = [];
+    images.forEach((img, i) => {
+        const mime = typeof img?.mime === "string" ? img.mime : "";
+        const ext = SCREENSHOT_MIME[mime];
+        if (!ext) {
+            errors.push(`image ${i + 1}: unsupported type "${mime || "unknown"}" — supported: ${Object.keys(SCREENSHOT_MIME).join(", ")}`);
+            return;
+        }
+        const data = typeof img?.data === "string" ? img.data : "";
+        let buf;
+        try {
+            buf = Buffer.from(data, "base64");
+        }
+        catch {
+            errors.push(`image ${i + 1}: invalid base64 data`);
+            return;
+        }
+        if (buf.length === 0) {
+            errors.push(`image ${i + 1}: image data is empty`);
+            return;
+        }
+        if (buf.length > MAX_SCREENSHOT_BYTES) {
+            errors.push(`image ${i + 1}: too large (max ${Math.round(MAX_SCREENSHOT_BYTES / 1024 / 1024)} MB)`);
+            return;
+        }
+        try {
+            mkdirSync(dir, { recursive: true });
+            const file = `${String(saved.length + 1).padStart(3, "0")}${ext}`;
+            const absPath = join(dir, file);
+            writeFileSync(absPath, buf);
+            saved.push({
+                absPath,
+                name: sanitizeName(typeof img?.name === "string" ? img.name : ""),
+                mime,
+                size: buf.length,
+            });
+        }
+        catch (err) {
+            errors.push(`image ${i + 1}: could not store — ${err instanceof Error ? err.message : err}`);
+        }
+    });
+    if (saved.length === 0) {
+        rmSync(dir, { recursive: true, force: true });
+        return { batchId: null, queued: 0, errors };
+    }
+    const id = randomUUID();
+    batches.set(id, { id, sessionKey, dir, images: saved, at: Date.now() });
+    // Cap per session: drop the session's oldest batches beyond the limit.
+    const forSession = [...batches.values()]
+        .filter((b) => b.sessionKey === sessionKey)
+        .sort((a, b) => a.at - b.at);
+    for (const old of forSession.slice(0, Math.max(0, forSession.length - MAX_BATCHES_PER_SESSION))) {
+        batches.delete(old.id);
+        rmSync(old.dir, { recursive: true, force: true });
+    }
+    return { batchId: id, queued: saved.length, errors };
+}
+/** Remove a just-queued batch (e.g. the PM send was rejected) and its files. */
+export function dropPmImages(batchId) {
+    if (!batchId)
+        return;
+    const batch = batches.get(batchId);
+    if (!batch)
+        return;
+    batches.delete(batchId);
+    rmSync(batch.dir, { recursive: true, force: true });
+}
+/**
+ * Attach the oldest pending batch whose PM session is still running to a
+ * freshly created task: move the files into the task's attachment folder
+ * under the usual `screenshot-N` names, reference them from the task body's
+ * `## Screenshots` section, and return the re-parsed task for the caller to
+ * apply to the index. Returns null when nothing is pending for a running
+ * session — the common case — or on any failure (best-effort; a failed
+ * attach never blocks the task creation itself, and the batch is dropped so
+ * a half-attached set cannot re-attach to a later task).
+ */
+export function attachPendingPmImages(config, task, isSessionRunning) {
+    prune();
+    const batch = [...batches.values()]
+        .filter((b) => isSessionRunning(b.sessionKey))
+        .sort((a, b) => a.at - b.at)[0];
+    if (!batch)
+        return null;
+    batches.delete(batch.id);
+    try {
+        const dir = attachmentsDir(config.root, config.workDir, task.id);
+        mkdirSync(dir, { recursive: true });
+        const taken = new Set(existsSync(dir) ? readdirSync(dir) : []);
+        const metas = [];
+        for (const img of batch.images) {
+            const ext = img.absPath.slice(img.absPath.lastIndexOf("."));
+            let next = 1;
+            while (taken.has(`screenshot-${next}${ext}`))
+                next++;
+            const file = `screenshot-${next}${ext}`;
+            renameSync(img.absPath, join(dir, file));
+            taken.add(file);
+            metas.push({
+                id: String(next),
+                name: img.name,
+                path: `${config.workDir.split("\\").join("/")}/.attachments/${task.id}/${file}`,
+                url: screenshotUrl(task.id, file),
+                size: img.size,
+                mime: img.mime,
+            });
+        }
+        rmSync(batch.dir, { recursive: true, force: true });
+        if (metas.length === 0)
+            return null;
+        return patchTaskFile(config, task.absPath, { addScreenshots: metas });
+    }
+    catch {
+        rmSync(batch.dir, { recursive: true, force: true });
+        return null;
+    }
+}
+/** Test hook: drop all in-memory batches (files under tmp roots are removed by the tests). */
+export function resetPmImages() {
+    for (const batch of batches.values()) {
+        rmSync(batch.dir, { recursive: true, force: true });
+    }
+    batches.clear();
+}

package/dist/server/pm-runs.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Live tracking of the PM agent's in-flight work per task (0335, 0381).
+ *
+ * Two distinct PM activities surface as the same "PM is working" indicator:
+ *
+ * - The freeform-create flesh-out — a fire-and-forget async closure in
+ *   `createFreeformTask` that never enters the AgentRunner, so nothing else
+ *   knows it is in flight and a fresh draft is visually indistinguishable
+ *   from an idle one. Tracked here by task id; the route marks it when the
+ *   run starts and clears it in a `finally` on every exit path.
+ * - The PM chat (task drawer's PM tab) — an AgentRunner session keyed by
+ *   `pm-task-v2:<taskId>` (plus a `::<email>` per-user suffix, 0248). The
+ *   route marks it when a message is accepted; the runner's `agent.exited`
+ *   event (success, error, or user interrupt — every exit path) clears it
+ *   via the emit hook in server.ts. Tracked by session key so two users can
+ *   chat about the same task concurrently without one exit dropping the
+ *   other's indicator.
+ *
+ * Deliberately in-memory (like `reviews.isRunning`): the state is transient —
+ * a server restart kills the runs along with the registry, so a stale
+ * "working" flag cannot outlive the process. Task-file frontmatter would be
+ * the wrong home for the same reason.
+ */
+/** Mark a task's draft as being fleshed out by the PM agent right now. */
+export declare function markPmWorking(taskId: string): void;
+/** Clear the in-flight marker — must be called on every run exit path. */
+export declare function clearPmWorking(taskId: string): void;
+/**
+ * Mark a PM chat session as live for a task (0381) — the runner accepted a
+ * message and a turn is starting (or queued behind maxConcurrentAgents).
+ */
+export declare function markPmChatSession(sessionKey: string, taskId: string): void;
+/** Clear one PM chat session — called when the runner reports its exit. */
+export declare function clearPmChatSession(sessionKey: string): void;
+/**
+ * The task id a runner session key belongs to, when that key is a PM chat
+ * session (`pm-task-v2:<id>` with an optional `::<email>` suffix) — null for
+ * anything else (engineer keys are bare task ids, review sessions are
+ * `review:<id>`, board chats have their own keys). Only the current
+ * `pm-task-v2` scheme is matched: the legacy `pm-task:` / `pm:` forms have no
+ * live sessions to clear.
+ */
+export declare function pmChatSessionTaskId(sessionKey: string): string | null;
+/** True while the PM is working on this task — freeform flesh-out or chat. */
+export declare function isPmWorking(taskId: string): boolean;
+/**
+ * Augment any task payload with the live PM flag — the same shape
+ * `withReviewStatus` uses for review activity. Applied to every endpoint the
+ * board/drawer reads (`/api/board`, `/api/index`, `/api/tasks`, `/api/tasks/:id`,
+ * the freeform-create responses) so a refresh/reconnect always reconciles the
+ * indicator, not just live SSE. Null passes through (route handlers previously
+ * serialized `index.getTask()`'s null directly).
+ */
+export declare function withPmWorking<T extends {
+    id: string;
+}>(task: T | null): (T & {
+    pmWorking: boolean;
+}) | null;

package/dist/server/pm-runs.js

@@ -0,0 +1,80 @@
+/**
+ * Live tracking of the PM agent's in-flight work per task (0335, 0381).
+ *
+ * Two distinct PM activities surface as the same "PM is working" indicator:
+ *
+ * - The freeform-create flesh-out — a fire-and-forget async closure in
+ *   `createFreeformTask` that never enters the AgentRunner, so nothing else
+ *   knows it is in flight and a fresh draft is visually indistinguishable
+ *   from an idle one. Tracked here by task id; the route marks it when the
+ *   run starts and clears it in a `finally` on every exit path.
+ * - The PM chat (task drawer's PM tab) — an AgentRunner session keyed by
+ *   `pm-task-v2:<taskId>` (plus a `::<email>` per-user suffix, 0248). The
+ *   route marks it when a message is accepted; the runner's `agent.exited`
+ *   event (success, error, or user interrupt — every exit path) clears it
+ *   via the emit hook in server.ts. Tracked by session key so two users can
+ *   chat about the same task concurrently without one exit dropping the
+ *   other's indicator.
+ *
+ * Deliberately in-memory (like `reviews.isRunning`): the state is transient —
+ * a server restart kills the runs along with the registry, so a stale
+ * "working" flag cannot outlive the process. Task-file frontmatter would be
+ * the wrong home for the same reason.
+ */
+const pmWorking = new Map();
+/** Active PM chat sessions: runner session key → the task it is about. */
+const pmChatWorking = new Map();
+/** Mark a task's draft as being fleshed out by the PM agent right now. */
+export function markPmWorking(taskId) {
+    pmWorking.set(taskId, { startedAt: new Date().toISOString() });
+}
+/** Clear the in-flight marker — must be called on every run exit path. */
+export function clearPmWorking(taskId) {
+    pmWorking.delete(taskId);
+}
+/**
+ * Mark a PM chat session as live for a task (0381) — the runner accepted a
+ * message and a turn is starting (or queued behind maxConcurrentAgents).
+ */
+export function markPmChatSession(sessionKey, taskId) {
+    pmChatWorking.set(sessionKey, { taskId, startedAt: new Date().toISOString() });
+}
+/** Clear one PM chat session — called when the runner reports its exit. */
+export function clearPmChatSession(sessionKey) {
+    pmChatWorking.delete(sessionKey);
+}
+/**
+ * The task id a runner session key belongs to, when that key is a PM chat
+ * session (`pm-task-v2:<id>` with an optional `::<email>` suffix) — null for
+ * anything else (engineer keys are bare task ids, review sessions are
+ * `review:<id>`, board chats have their own keys). Only the current
+ * `pm-task-v2` scheme is matched: the legacy `pm-task:` / `pm:` forms have no
+ * live sessions to clear.
+ */
+export function pmChatSessionTaskId(sessionKey) {
+    const m = sessionKey.match(/^pm-task-v2:([^:]+)(?:::.*)?$/i);
+    return m ? m[1] || null : null;
+}
+/** True while the PM is working on this task — freeform flesh-out or chat. */
+export function isPmWorking(taskId) {
+    if (pmWorking.has(taskId))
+        return true;
+    for (const { taskId: chatTaskId } of pmChatWorking.values()) {
+        if (chatTaskId === taskId)
+            return true;
+    }
+    return false;
+}
+/**
+ * Augment any task payload with the live PM flag — the same shape
+ * `withReviewStatus` uses for review activity. Applied to every endpoint the
+ * board/drawer reads (`/api/board`, `/api/index`, `/api/tasks`, `/api/tasks/:id`,
+ * the freeform-create responses) so a refresh/reconnect always reconciles the
+ * indicator, not just live SSE. Null passes through (route handlers previously
+ * serialized `index.getTask()`'s null directly).
+ */
+export function withPmWorking(task) {
+    if (!task)
+        return null;
+    return { ...task, pmWorking: isPmWorking(task.id) };
+}

package/dist/server/preview.d.ts

@@ -0,0 +1,174 @@
+import type { RepoOSConfig, Task } from "../core/types.js";
+import type { RepoEvent } from "./live-index.js";
+export interface PreviewInfo {
+    port: number;
+    url: string;
+    startedAt: string;
+    pid: number;
+    /**
+     * Path polled on the preview URL for readiness (#0362): `/` (or the target's
+     * override). Always a project-declared path since #0370 removed the implicit
+     * `repoos serve` target.
+     */
+    readyPath?: string;
+    /**
+     * Resolved custom command the preview child was started with (#0362), used to
+     * identify the process during boot-time orphan cleanup. Every preview now
+     * carries one — the implicit `repoos serve` fallback was removed (#0370).
+     */
+    command?: string;
+    /**
+     * Human label for which preview target ran (#0362 review): the matched
+     * `[[preview.targets]]` name, or "default" for the bare `[preview] command`.
+     * Aids debugging on a foreign repo with several configured targets.
+     */
+    label?: string;
+    /**
+     * True when the preview child leads its own process group (POSIX custom
+     * commands), so stop/reap signals must target the group (`-pid`) to take the
+     * shell's whole tree down with it.
+     */
+    processGroup?: boolean;
+}
+export interface PreviewResult {
+    ok: boolean;
+    port?: number;
+    url?: string;
+    /** Readiness path for the started preview, so callers probe the right endpoint. */
+    readyPath?: string;
+    /** Which preview target ran (#0362 review) — see `PreviewInfo.label`. */
+    label?: string;
+    error?: string;
+}
+/** Result of a trusted server-side health/static probe of a preview URL (#0121). */
+export interface PreviewProbe {
+    ok: boolean;
+    detail?: string;
+    error?: string;
+}
+/** The preview target resolved for one task (#0362): a project-declared
+ *  shell command selected by the task's `area`. */
+export type PreviewTarget = {
+    kind: "command";
+    /** Human label for diagnostics: the target name, or "default". */
+    label: string;
+    command: string;
+    cwd?: string;
+    readyPath: string;
+    /** How long to wait for this target before giving up (ms). See PreviewTargetConfig.readyTimeoutMs. */
+    readyTimeoutMs: number;
+};
+/** Resolution result: a runnable target, or a clean "nothing configured". */
+export type PreviewTargetResolution = PreviewTarget | {
+    kind: "none";
+    reason: string;
+};
+/**
+ * A selectable preview target for the UI (#0379). Every configured target whose
+ * `areas` include the task's `area` is a candidate; when more than one matches,
+ * the drawer must let the user choose rather than silently previewing the first.
+ */
+export interface PreviewTargetOption {
+    /** Human label shown in the drawer and recorded on the run: the target's
+     *  `name`, or "default" for the bare `[preview] command`. */
+    name: string;
+    /** Task areas this target declared (empty for the default command). */
+    areas: string[];
+}
+/** Options for `PreviewManager.start` (#0379). */
+export interface PreviewStartOptions {
+    /**
+     * Permit starting the config-order first match when the task's area resolves
+     * to more than one target. The UI never sets this — it must make the user
+     * choose — so an ambiguous start with no `targetName` is rejected. The
+     * agent-request path has no picker, so it opts in and reports the chosen
+     * label in its transcript instead of claiming a choice was made.
+     */
+    allowAmbiguous?: boolean;
+}
+/**
+ * The preview targets the UI can offer for `task` (#0379). One entry for the
+ * common single-match case; several when the task's `area` is claimed by more
+ * than one `[[preview.targets]]`; empty when nothing is configured for it.
+ * Exported for the board/task routes and tests.
+ */
+export declare function previewTargetOptions(config: RepoOSConfig, task: Task): PreviewTargetOption[];
+/**
+ * Decide how to preview `task` from the repo's `[preview]` config (#0362).
+ *
+ * Precedence: named targets whose `areas` include the task's `area` (config
+ * order); then a default `[preview] command`; then a `none` result with an
+ * actionable message (never a spawn failure). A project with no `[preview]`
+ * config at all is the same clean `none`, not an implicit RepoOS-board preview
+ * (#0370). When `targetName` is given — the UI's picker choice (#0379) — that
+ * exact target is used; an unknown name is a clean `none`, never a silent
+ * fallback to a different target. Exported for tests.
+ */
+export declare function resolvePreviewTarget(config: RepoOSConfig, task: Task, targetName?: string): PreviewTargetResolution;
+/**
+ * Probe a live preview URL from the trusted server side (#0121): the target's
+ * configured readiness path (`/` by default — #0362). A healthy readiness
+ * endpoint is enough for a pass. Used when a sandboxed agent cannot open the
+ * returned URL itself.
+ */
+export declare function probePreview(url: string, readyPath?: string): Promise<PreviewProbe>;
+export declare class PreviewManager {
+    private registry;
+    private readonly file;
+    private readonly config;
+    private readonly emit;
+    /** Last stderr lines from a still-booting preview, for diagnostics. */
+    private bootErrors;
+    /** Starts still in flight per task, so concurrent calls never double-spawn. */
+    private inflight;
+    constructor(config: RepoOSConfig, emit: (e: RepoEvent) => void);
+    /**
+     * PIDs of preview servers this manager started. Used by the serve-process
+     * census (#0216) so a legitimate preview is never counted as a stray.
+     */
+    knownPids(): number[];
+    get(taskId: string): PreviewInfo | null;
+    /**
+     * Start a preview for a task: resolve its preview target from `[preview]`
+     * config (#0362), allocate an ephemeral port, spawn the project-declared
+     * command rooted at the worktree, and wait for it to come up. Returns
+     * `{ ok, port, url }` or a human-readable error.
+     *
+     * Every check happens BEFORE anything starts: the task id must resolve, the
+     * task must be in an allowed state (active/review), it must carry a
+     * registered branch, and that branch must have a real linked worktree. The
+     * worktree path is resolved from the task's own branch — never an
+     * agent-supplied path (ADR-0005). Repeated requests are idempotent and
+     * return the existing healthy preview.
+     *
+     * When the task's area matches more than one target (#0379), `targetName`
+     * picks the one the user chose in the drawer. Starting without a choice is
+     * rejected (never a silent first pick) unless the caller is the agent-request
+     * path, which opts in via `allowAmbiguous` and reports the label it got.
+     */
+    start(task: Task, targetName?: string, opts?: PreviewStartOptions): Promise<PreviewResult>;
+    private doStart;
+    /** Stop a task's preview. Idempotent: stopping nothing is a no-op success. */
+    stop(taskId: string): Promise<void>;
+    /** Stop every preview — used on main-server shutdown. */
+    stopAll(): Promise<void>;
+    /**
+     * Boot-time cleanup: kill any preview servers a previous (crashed) main
+     * server recorded and left running, then drop the registry file. Skipped in
+     * preview children (they serve the worktree, never the main registry).
+     */
+    cleanupOrphans(): void;
+    /**
+     * Enforce the concurrent cap (#0198): when at `MAX_PREVIEWS` and the task
+     * being started isn't already running, terminate the OLDEST running preview
+     * (FIFO) before a new one spawns. Logs the eviction with task id + timestamp.
+     */
+    private evictIfAtCapacity;
+    /** Best-effort lifecycle log — task id and an ISO-8601 timestamp (#0198). */
+    private logLifecycle;
+    private spawnPreview;
+    /** Graceful SIGTERM, then SIGKILL after a short grace period. */
+    private kill;
+    /** Persist the registry so a crashed main server's previews can be reaped. */
+    private persist;
+}