@repo-os/repoos 0.5.45

package/dist/core/sysmem.js

@@ -0,0 +1,55 @@
+/**
+ * Memory facts the OS won't give you straight. `os.freemem()` counts only
+ * fully-idle pages — on macOS that is near-zero at all times because the kernel
+ * fills unused RAM with reclaimable cache and inactive pages. This module
+ * reports the number that actually matters: how much the OS can hand back on
+ * demand without swapping.
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { freemem, platform } from "node:os";
+function run(cmd, args) {
+    try {
+        return execFileSync(cmd, args, {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 4000,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Bytes the OS can reclaim on demand without swapping:
+ * free + inactive + speculative + purgeable (macOS, via `vm_stat`), or
+ * `MemAvailable` (Linux, via `/proc/meminfo`). Falls back to `os.freemem()`
+ * when the platform probe is unavailable or fails.
+ */
+export function availableMemBytes() {
+    const p = platform();
+    if (p === "darwin") {
+        const out = run("vm_stat", []);
+        if (out) {
+            const pageSize = Number(out.match(/page size of (\d+) bytes/)?.[1]) || 4096;
+            const pages = (label) => Number(out.match(new RegExp(`${label}:\\s+(\\d+)\\.`))?.[1]) || 0;
+            const reclaimable = pages("Pages free") +
+                pages("Pages inactive") +
+                pages("Pages speculative") +
+                pages("Pages purgeable");
+            if (reclaimable > 0)
+                return reclaimable * pageSize;
+        }
+    }
+    else if (p === "linux") {
+        try {
+            const avail = readFileSync("/proc/meminfo", "utf8").match(/^MemAvailable:\s+(\d+)\s+kB/m);
+            if (avail)
+                return Number(avail[1]) * 1024;
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    return freemem();
+}

package/dist/core/tailscale.d.ts

@@ -0,0 +1,2 @@
+/** This machine's Tailscale IPv4 address, or null if Tailscale isn't installed/running. */
+export declare function detectTailscaleIPv4(): string | null;

package/dist/core/tailscale.js

@@ -0,0 +1,19 @@
+/**
+ * Best-effort Tailscale detection, used to pick a sane default bind host.
+ */
+import { execFileSync } from "node:child_process";
+/** This machine's Tailscale IPv4 address, or null if Tailscale isn't installed/running. */
+export function detectTailscaleIPv4() {
+    try {
+        const out = execFileSync("tailscale", ["ip", "-4"], {
+            timeout: 1500,
+            stdio: ["ignore", "pipe", "ignore"],
+        })
+            .toString()
+            .trim();
+        return out || null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/task.d.ts

@@ -0,0 +1,53 @@
+import { type Task, type Status, type Assignee, type TaskGitInfo } from "./types.js";
+export declare const ACTIVITY_HEADING = "## Activity";
+/** User-attached screenshots section (0123). Rendered into the body, kept before `## Activity`. */
+export declare const SCREENSHOTS_HEADING = "## Screenshots";
+/** The user's verbatim freeform prompt, preserved so an agent rewrite can't lose it. */
+export declare const ORIGINAL_PROMPT_HEADING = "## Original prompt";
+/** ISO-8601 UTC timestamp to the second, e.g. 2026-06-01T09:14:02Z. */
+export declare function utcTimestamp(): string;
+/**
+ * Normalize a legacy date-only or partial timestamp to full ISO-8601 UTC.
+ * `2026-06-01` → `2026-06-01T00:00:00Z`. Null passthrough.
+ */
+export declare function normalizeTimestamp(value: string | null): string | null;
+/**
+ * Append a single activity entry to the body's Activity section.
+ * Creates the section if it does not exist. The Activity section is always
+ * the last thing in the body — append-only invariant.
+ */
+export declare function appendActivityEntry(body: string, line: string): string;
+/**
+ * Extract a top-level `## Heading` section from a body — the heading line
+ * through the last line before the next `## ` heading (or EOF), trimmed of
+ * surrounding blank lines. Returns null when the heading is absent.
+ */
+export declare function extractSection(body: string, heading: string): string | null;
+/**
+ * Remove the `## Heading` section (see {@link extractSection}) from a body,
+ * collapsing the blank lines it leaves behind. Unchanged when the heading is
+ * absent.
+ */
+export declare function removeSection(body: string, heading: string): string;
+/**
+ * Single change-recording helper. Every mutation path MUST call this.
+ * Stamps `updated_at` and appends an activity log entry onto `task.body`.
+ *
+ * @param task  The task to record a change on (mutated in-place).
+ * @param entry The activity line content after the timestamp,
+ *              e.g. `status inbox→ready · nick`.
+ */
+export declare function recordChange(task: Task, entry: string): void;
+/** Latest successful-close-out timestamp recorded in the append-only activity log. */
+export declare function releasedAtFromActivity(body: string): string | null;
+export interface ParseTaskArgs {
+    content: string;
+    absPath: string;
+    root: string;
+    defaultStatus: Status;
+    defaultAssignee: Assignee;
+    git?: TaskGitInfo;
+}
+export declare function parseTask(args: ParseTaskArgs): Task;
+/** Build the file content for a Task, preserving unknown frontmatter. */
+export declare function serializeTask(task: Task): string;

package/dist/core/task.js

@@ -0,0 +1,310 @@
+/**
+ * Turn a markdown file (content + path) into a normalized Task, and turn a
+ * Task back into file content for writing. Normalization is forgiving: missing
+ * fields get sensible derived defaults so even a bare markdown file becomes a
+ * usable task.
+ */
+import { basename, relative } from "node:path";
+import { parseDocument, serializeDocument } from "./frontmatter.js";
+import { STATUSES } from "./types.js";
+import { emptyGitInfo } from "./git.js";
+/** Canonical frontmatter key order, so writes produce tidy, stable diffs. */
+const KEY_ORDER = [
+    "id",
+    "title",
+    "type",
+    "status",
+    "needs_input",
+    "needs_input_reason",
+    "needs_merge",
+    "no_source_change",
+    "priority",
+    "area",
+    "assigned_to",
+    "created_by",
+    "branch",
+    "tags",
+    "agent_override",
+    "cli_override",
+    "model_override",
+    "pm_agent_override",
+    "pm_cli_override",
+    "pm_model_override",
+    "review_agent_override",
+    "review_cli_override",
+    "review_model_override",
+    "hotfix",
+    "hotfix_target",
+    "created_at",
+    "updated_at",
+];
+export const ACTIVITY_HEADING = "## Activity";
+/** User-attached screenshots section (0123). Rendered into the body, kept before `## Activity`. */
+export const SCREENSHOTS_HEADING = "## Screenshots";
+/** The user's verbatim freeform prompt, preserved so an agent rewrite can't lose it. */
+export const ORIGINAL_PROMPT_HEADING = "## Original prompt";
+/**
+ * A release is a successful close-out event, not any prose mentioning a
+ * release. `markTaskReleased` is the sole writer of this exact marker.
+ */
+const RELEASE_ACTIVITY = /^- (\d{4}-\d{2}-\d{2}T[^\s]+) · status [a-z]+→done, release:success\r?$/gmu;
+/** ISO-8601 UTC timestamp to the second, e.g. 2026-06-01T09:14:02Z. */
+export function utcTimestamp() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/**
+ * Normalize a legacy date-only or partial timestamp to full ISO-8601 UTC.
+ * `2026-06-01` → `2026-06-01T00:00:00Z`. Null passthrough.
+ */
+export function normalizeTimestamp(value) {
+    if (!value)
+        return null;
+    if (/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return `${value}T00:00:00Z`;
+    return value;
+}
+/**
+ * Append a single activity entry to the body's Activity section.
+ * Creates the section if it does not exist. The Activity section is always
+ * the last thing in the body — append-only invariant.
+ */
+export function appendActivityEntry(body, line) {
+    const trimmed = body.replace(/\s+$/, "");
+    const headingIndex = trimmed.lastIndexOf(`\n${ACTIVITY_HEADING}\n`);
+    if (headingIndex === -1) {
+        return `${trimmed}\n\n${ACTIVITY_HEADING}\n\n${line}\n`;
+    }
+    return `${trimmed}\n${line}\n`;
+}
+/** The line index where a top-level `## Heading` section starts, or -1. */
+function sectionStart(lines, heading) {
+    return lines.findIndex((l) => l.trim() === heading);
+}
+/** The line index of the next top-level `## ` heading after `from`, or `lines.length`. */
+function nextSection(lines, from) {
+    for (let i = from; i < lines.length; i++) {
+        if (/^##\s/.test(lines[i].trim()))
+            return i;
+    }
+    return lines.length;
+}
+/**
+ * Extract a top-level `## Heading` section from a body — the heading line
+ * through the last line before the next `## ` heading (or EOF), trimmed of
+ * surrounding blank lines. Returns null when the heading is absent.
+ */
+export function extractSection(body, heading) {
+    const lines = body.split("\n");
+    const start = sectionStart(lines, heading);
+    if (start === -1)
+        return null;
+    return lines
+        .slice(start, nextSection(lines, start + 1))
+        .join("\n")
+        .trim();
+}
+/**
+ * Remove the `## Heading` section (see {@link extractSection}) from a body,
+ * collapsing the blank lines it leaves behind. Unchanged when the heading is
+ * absent.
+ */
+export function removeSection(body, heading) {
+    const lines = body.split("\n");
+    const start = sectionStart(lines, heading);
+    if (start === -1)
+        return body;
+    const end = nextSection(lines, start + 1);
+    const before = lines.slice(0, start).join("\n").replace(/\s+$/, "");
+    const after = lines.slice(end).join("\n").replace(/^\s+/, "");
+    return [before, after].filter(Boolean).join("\n\n");
+}
+/**
+ * Single change-recording helper. Every mutation path MUST call this.
+ * Stamps `updated_at` and appends an activity log entry onto `task.body`.
+ *
+ * @param task  The task to record a change on (mutated in-place).
+ * @param entry The activity line content after the timestamp,
+ *              e.g. `status inbox→ready · nick`.
+ */
+export function recordChange(task, entry) {
+    task.updated_at = utcTimestamp();
+    task.body = appendActivityEntry(task.body, `- ${task.updated_at} · ${entry}`);
+}
+/** Latest successful-close-out timestamp recorded in the append-only activity log. */
+export function releasedAtFromActivity(body) {
+    let releasedAt = null;
+    for (const match of body.matchAll(RELEASE_ACTIVITY))
+        releasedAt = match[1];
+    return releasedAt;
+}
+function deriveIdFromFilename(file) {
+    const name = basename(file).replace(/\.[^.]+$/, "");
+    const m = name.match(/^(\d{2,})/);
+    if (m)
+        return m[1];
+    return name;
+}
+function deriveTitleFromBody(body, fallback) {
+    const h1 = body.match(/^\s*#\s+(.+)$/m);
+    if (h1)
+        return h1[1].trim();
+    return fallback;
+}
+function normalizeStatus(raw, fallback) {
+    const s = String(raw ?? "").toLowerCase();
+    return STATUSES.includes(s) ? s : fallback;
+}
+function resolveAssignee(raw) {
+    const v = raw.toLowerCase().trim();
+    if (v === "ai" || v === "agent")
+        return "ai";
+    if (v === "" || v === "unassigned" || v === "none")
+        return "unassigned";
+    return "human";
+}
+export function parseTask(args) {
+    const { content, absPath, root, defaultStatus, defaultAssignee } = args;
+    const { data, body } = parseDocument(content);
+    const relPath = relative(root, absPath).split("\\").join("/");
+    const id = String(data.id ?? deriveIdFromFilename(absPath));
+    const title = String(data.title ?? deriveTitleFromBody(body, id));
+    const assignedTo = String(data.assigned_to ?? "");
+    const assignee = resolveAssignee(assignedTo || (defaultAssignee === "unassigned" ? "" : defaultAssignee));
+    // collect unknown keys to preserve on write
+    const known = new Set(KEY_ORDER);
+    const extra = {};
+    for (const [k, v] of Object.entries(data)) {
+        if (!known.has(k))
+            extra[k] = v;
+    }
+    // Per-task agent override fields
+    const agentOverride = typeof data.agent_override === "string" && data.agent_override ? data.agent_override : null;
+    const cliOverride = typeof data.cli_override === "string" && data.cli_override ? data.cli_override : null;
+    const modelOverride = typeof data.model_override === "string" && data.model_override ? data.model_override : null;
+    // Per-task PM agent override fields
+    const pmAgentOverride = typeof data.pm_agent_override === "string" && data.pm_agent_override
+        ? data.pm_agent_override
+        : null;
+    const pmCliOverride = typeof data.pm_cli_override === "string" && data.pm_cli_override ? data.pm_cli_override : null;
+    const pmModelOverride = typeof data.pm_model_override === "string" && data.pm_model_override
+        ? data.pm_model_override
+        : null;
+    // Per-task reviewer agent override fields
+    const reviewAgentOverride = typeof data.review_agent_override === "string" && data.review_agent_override
+        ? data.review_agent_override
+        : null;
+    const reviewCliOverride = typeof data.review_cli_override === "string" && data.review_cli_override
+        ? data.review_cli_override
+        : null;
+    const reviewModelOverride = typeof data.review_model_override === "string" && data.review_model_override
+        ? data.review_model_override
+        : null;
+    // read created_at with fallback to deprecated created
+    const created_at = data.created_at
+        ? String(data.created_at)
+        : data.created
+            ? String(data.created)
+            : null;
+    // read updated_at with fallback to deprecated updated
+    const updated_at = data.updated_at
+        ? String(data.updated_at)
+        : data.updated
+            ? String(data.updated)
+            : null;
+    return {
+        id,
+        title,
+        type: String(data.type ?? "feature"),
+        status: normalizeStatus(data.status, "inbox"),
+        needsInput: data.needs_input === true,
+        needsInputReason: typeof data.needs_input_reason === "string" ? data.needs_input_reason : undefined,
+        needsMerge: data.needs_merge === true,
+        noSourceChange: data.no_source_change === true,
+        priority: String(data.priority ?? "p2"),
+        area: String(data.area ?? "general"),
+        assignee,
+        assignedTo: assignedTo || (assignee === "unassigned" ? "" : assignee),
+        createdBy: String(data.created_by ?? ""),
+        branch: String(data.branch ?? ""),
+        tags: Array.isArray(data.tags) ? data.tags.map(String) : [],
+        created_at,
+        updated_at,
+        releasedAt: releasedAtFromActivity(body),
+        path: relPath,
+        absPath,
+        body,
+        extra,
+        agentOverride,
+        cliOverride,
+        modelOverride,
+        pmAgentOverride,
+        pmCliOverride,
+        pmModelOverride,
+        reviewAgentOverride,
+        reviewCliOverride,
+        reviewModelOverride,
+        hotfix: data.hotfix === true ? true : undefined,
+        hotfixTarget: data.hotfix === true ? (data.hotfix_target === "main" ? "main" : "branch") : undefined,
+        git: args.git ?? emptyGitInfo(),
+    };
+}
+/** Build the file content for a Task, preserving unknown frontmatter. */
+export function serializeTask(task) {
+    const data = {
+        id: task.id,
+        title: task.title,
+        type: task.type,
+        status: task.status,
+        priority: task.priority,
+        area: task.area,
+        assigned_to: task.assignedTo || (task.assignee === "ai" ? "ai" : ""),
+        created_by: task.createdBy,
+        branch: task.branch,
+    };
+    if (task.tags.length)
+        data.tags = task.tags;
+    // Only ever write `needs_input` / `needs_merge` when true — false is the
+    // default and is never persisted, so clearing the flag removes the key.
+    // The reason is only ever meaningful alongside the flag itself — clearing
+    // needsInput (or never setting a reason) must never leave a stale reason
+    // behind to be misread on a later re-escalation.
+    if (task.needsInput) {
+        data.needs_input = true;
+        if (task.needsInputReason)
+            data.needs_input_reason = task.needsInputReason;
+    }
+    if (task.needsMerge)
+        data.needs_merge = true;
+    if (task.noSourceChange)
+        data.no_source_change = true;
+    if (task.agentOverride)
+        data.agent_override = task.agentOverride;
+    if (task.cliOverride)
+        data.cli_override = task.cliOverride;
+    if (task.modelOverride)
+        data.model_override = task.modelOverride;
+    if (task.pmAgentOverride)
+        data.pm_agent_override = task.pmAgentOverride;
+    if (task.pmCliOverride)
+        data.pm_cli_override = task.pmCliOverride;
+    if (task.pmModelOverride)
+        data.pm_model_override = task.pmModelOverride;
+    if (task.reviewAgentOverride)
+        data.review_agent_override = task.reviewAgentOverride;
+    if (task.reviewCliOverride)
+        data.review_cli_override = task.reviewCliOverride;
+    if (task.reviewModelOverride)
+        data.review_model_override = task.reviewModelOverride;
+    if (task.hotfix) {
+        data.hotfix = true;
+        data.hotfix_target = task.hotfixTarget ?? "branch";
+    }
+    if (task.created_at)
+        data.created_at = normalizeTimestamp(task.created_at);
+    if (task.updated_at)
+        data.updated_at = normalizeTimestamp(task.updated_at);
+    // re-attach preserved unknown keys
+    for (const [k, v] of Object.entries(task.extra))
+        data[k] = v;
+    return serializeDocument(data, task.body, KEY_ORDER);
+}

package/dist/core/toml-line.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Line-level helpers shared by RepoOS's small TOML readers and writers
+ * (config.ts, tunnel.ts).
+ *
+ * The readers used to strip comments with `line.replace(/#.*$/, "")`, which
+ * also cut quoted values at the first `#`. The Agents page then saved that
+ * cut value back, which is how the reviewer's instructions in repoos.toml lost
+ * everything after "with exactly `" (the next character was the `#` of
+ * `## Verdict`). Anything with a `#0348`-style task reference hit the same.
+ */
+/** Drop a trailing `# comment`, ignoring `#` inside "double" or 'single' quoted strings. */
+export declare function stripTomlComment(line: string): string;
+/**
+ * Turn a quoted TOML scalar back into its string. Double-quoted values are
+ * decoded with JSON rules, which is exactly how the writers encode them
+ * (`JSON.stringify`), so `\"` and `\\` round-trip instead of gaining a
+ * backslash on every save. A value that isn't valid JSON (for example a
+ * hand-written literal `\d`) falls back to stripping the outer quotes.
+ */
+export declare function unquoteTomlString(s: string): string;

package/dist/core/toml-line.js

@@ -0,0 +1,52 @@
+/**
+ * Line-level helpers shared by RepoOS's small TOML readers and writers
+ * (config.ts, tunnel.ts).
+ *
+ * The readers used to strip comments with `line.replace(/#.*$/, "")`, which
+ * also cut quoted values at the first `#`. The Agents page then saved that
+ * cut value back, which is how the reviewer's instructions in repoos.toml lost
+ * everything after "with exactly `" (the next character was the `#` of
+ * `## Verdict`). Anything with a `#0348`-style task reference hit the same.
+ */
+/** Drop a trailing `# comment`, ignoring `#` inside "double" or 'single' quoted strings. */
+export function stripTomlComment(line) {
+    let quote = null;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (quote) {
+            if (quote === '"' && ch === "\\") {
+                i++; // skip the escaped character, including an escaped quote
+                continue;
+            }
+            if (ch === quote)
+                quote = null;
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+        }
+        else if (ch === "#") {
+            return line.slice(0, i);
+        }
+    }
+    return line;
+}
+/**
+ * Turn a quoted TOML scalar back into its string. Double-quoted values are
+ * decoded with JSON rules, which is exactly how the writers encode them
+ * (`JSON.stringify`), so `\"` and `\\` round-trip instead of gaining a
+ * backslash on every save. A value that isn't valid JSON (for example a
+ * hand-written literal `\d`) falls back to stripping the outer quotes.
+ */
+export function unquoteTomlString(s) {
+    if (s.length >= 2 && s.startsWith('"') && s.endsWith('"')) {
+        try {
+            const decoded = JSON.parse(s);
+            if (typeof decoded === "string")
+                return decoded;
+        }
+        catch {
+            /* not JSON-compatible: fall through */
+        }
+    }
+    return s.replace(/^["']|["']$/g, "");
+}

package/dist/core/toml-validate.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Dependency-free TOML syntax validator (#0375).
+ *
+ * The Settings page's raw editor writes `repoos.toml` verbatim, so a malformed
+ * save must be rejected *before* it reaches disk — `loadConfig`'s reader is
+ * deliberately forgiving (it skips lines it can't parse), which would turn a
+ * typo into a silently-ignored config instead of an error the user can see.
+ *
+ * This is a validator, not a parser: it walks the document and reports the
+ * first structural problem it finds (unterminated string/array, missing `=`,
+ * bad table header, invalid scalar) with a 1-based line number. It accepts the
+ * TOML shapes RepoOS itself emits plus the common hand-written ones (dotted
+ * and quoted keys, literal strings, single-line arrays, dates/times,
+ * hex/octal/binary numbers). It deliberately does not enforce key uniqueness
+ * or table-redefinition rules — those are valid-TOML concerns that never
+ * affect what `loadConfig` reads, and rejecting on them would make the escape
+ * hatch stricter than the loader it feeds.
+ *
+ * Crucially, it rejects the *valid TOML* shapes that `parseFlatToml`
+ * (`config.ts`) cannot read: multi-line strings, multi-line arrays, and inline
+ * tables. Those would otherwise sail through a save and then be silently
+ * misread (the first line of a multi-line array parses as the string `"["`,
+ * an inline table as a plain string), so a whole save could take no effect
+ * with no error — the exact silent-config failure this gate exists to stop.
+ */
+export interface TomlValidationResult {
+    ok: boolean;
+    /** Human-readable reason, without a line prefix. Present when `ok` is false. */
+    error?: string;
+    /** 1-based line the problem was found on. Present when `ok` is false. */
+    line?: number;
+}
+/**
+ * Validate a TOML document's syntax. Returns `{ ok: true }` when the whole
+ * document is structurally well-formed, or `{ ok: false, error, line }` with
+ * the first problem found. Never throws on malformed input.
+ */
+export declare function validateToml(source: string): TomlValidationResult;
+/**
+ * Format a validation failure for display, with the line folded into the
+ * message so callers that only carry a string (the HTTP JSON error, the store)
+ * still surface it.
+ */
+export declare function formatTomlError(result: TomlValidationResult): string;