@repo-os/repoos 0.5.45

package/dist/core/indexer.d.ts

@@ -0,0 +1,33 @@
+import { type RepoIndex, type RepoOSConfig } from "./types.js";
+import { type WorktreeDirtyCache } from "./git.js";
+export declare function buildIndex(config: RepoOSConfig): RepoIndex;
+/**
+ * Async counterpart of `buildIndex`. Identical result, but the per-task git
+ * enrichment (last commit + worktree status) runs CONCURRENTLY instead of one
+ * task at a time on the main thread — `buildIndex`'s synchronous git spawns
+ * each block the event loop for a full OS round-trip, so N tasks cost N
+ * serial round-trips no matter how idle the machine is. With 260+ tasks that
+ * was several seconds of RepoOS's slow boot on top of the redundant spawns
+ * fixed above (#0271 follow-up). Used by the server's startup path, which can
+ * let `listen()` proceed while this populates the index in the background;
+ * `buildIndex` remains for callers (the CLI) that want a synchronous result.
+ *
+ * `opts.fastWorktreeStatus` skips the per-worktree `git status` entirely and
+ * reports each task's `dirty` from the persisted cache plus its ahead count.
+ * The server passes this at boot and follows up with
+ * `LiveIndex.reconcileWorktreeStatus()` a moment later, trading a few seconds
+ * of a possibly-stale "uncommitted changes" dot for a fast first paint.
+ */
+export declare function buildIndexAsync(config: RepoOSConfig, opts?: {
+    fastWorktreeStatus?: boolean;
+}): Promise<RepoIndex>;
+export declare function indexCachePath(config: RepoOSConfig): string;
+/**
+ * Load the persisted per-branch working-tree dirtiness so a rebuild can skip
+ * `git status` for worktrees whose HEAD has not moved. Always safe: a missing,
+ * malformed, or stale file just means more `git status` calls this run.
+ */
+export declare function readWorktreeDirtyCache(config: RepoOSConfig): WorktreeDirtyCache;
+export declare function writeWorktreeDirtyCache(config: RepoOSConfig, cache: WorktreeDirtyCache): void;
+export declare function writeIndexCache(config: RepoOSConfig, index: RepoIndex): void;
+export declare function readIndexCache(config: RepoOSConfig): RepoIndex | null;

package/dist/core/indexer.js

@@ -0,0 +1,282 @@
+/**
+ * The indexer. Walks the work directory, parses every task file, enriches with
+ * best-effort git facts, sorts deterministically, and produces a RepoIndex.
+ *
+ * The index is DERIVED: it can be thrown away and rebuilt from files at any
+ * time. It is written to <cacheDir>/index.json purely as a cache for fast reads
+ * (and, later, for the Stage 2 server to serve without re-walking on every
+ * request).
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { extname, join } from "node:path";
+import { STATUSES, PRIORITIES, } from "./types.js";
+import { parseTask } from "./task.js";
+import { parseDocument } from "./frontmatter.js";
+import { isGitRepo, localBranches, lastCommitsForDir, lastCommitsForDirAsync, worktreeStatus, worktreePaths, currentBranch, emptyGitInfo, resolveWorktreeStatuses, } from "./git.js";
+const INDEX_VERSION = 1;
+function walkFiles(dir, exts, acc = []) {
+    if (!existsSync(dir))
+        return acc;
+    for (const entry of readdirSync(dir)) {
+        if (entry.startsWith("."))
+            continue;
+        const full = join(dir, entry);
+        const st = statSync(full);
+        if (st.isDirectory()) {
+            walkFiles(full, exts, acc);
+        }
+        else if (exts.includes(extname(entry))) {
+            acc.push(full);
+        }
+    }
+    return acc;
+}
+function priorityRank(p) {
+    const i = PRIORITIES.indexOf(p);
+    return i === -1 ? PRIORITIES.length : i;
+}
+function statusRank(s) {
+    return STATUSES.indexOf(s);
+}
+export function buildIndex(config) {
+    const workPath = join(config.root, config.workDir);
+    const files = walkFiles(workPath, config.taskExtensions);
+    const useGit = isGitRepo(config.root);
+    const branches = useGit ? localBranches(config.root) : new Set();
+    const worktrees = useGit ? worktreePaths(config.root) : new Map();
+    // Fetched once and passed to every `worktreeStatus` call below — otherwise
+    // each of the N tasks with a branch re-runs `git worktree list` and
+    // `git rev-parse HEAD` itself, turning a 260-task index build into
+    // hundreds of redundant git spawns (#0271 follow-up: this was a large
+    // share of RepoOS's 20-30s boot time).
+    const baseBranch = useGit ? currentBranch(config.root) : null;
+    // One `git log` pass for every task file's last commit, instead of one
+    // history walk per file inside the loop below (#0271 follow-up).
+    const lastCommits = useGit
+        ? lastCommitsForDir(config.root, config.workDir)
+        : new Map();
+    let skippedTaskFiles = 0;
+    const tasks = files.flatMap((absPath) => {
+        const content = readFileSync(absPath, "utf8");
+        // Reject files with no explicit `id` in frontmatter — the API always sets
+        // it, so a missing id means a human or AI agent hand-wrote the file. These
+        // get an opaque derived id and would silently pollute the task list.
+        const { data } = parseDocument(content);
+        if (!("id" in data)) {
+            skippedTaskFiles++;
+            return [];
+        }
+        const base = parseTask({
+            content,
+            absPath,
+            root: config.root,
+            defaultStatus: config.defaultStatus,
+            defaultAssignee: config.defaultAssignee,
+            git: emptyGitInfo(),
+        });
+        if (useGit) {
+            const { subject, date } = lastCommits.get(base.path) ?? {
+                subject: null,
+                date: null,
+            };
+            const wt = base.branch
+                ? worktreeStatus(config.root, base.branch, { worktrees, baseBranch })
+                : { path: null, dirty: false };
+            base.git = {
+                branchExists: base.branch ? branches.has(base.branch) : false,
+                worktreeExists: base.branch ? worktrees.has(base.branch) : false,
+                lastCommit: subject,
+                lastCommitAt: date,
+                worktreePath: wt.path,
+                dirty: wt.dirty,
+            };
+        }
+        return [base];
+    });
+    if (skippedTaskFiles > 0) {
+        console.warn(`[repoos] skipped ${skippedTaskFiles} task file(s) with no \`id\` in frontmatter — ` +
+            `use the API (POST /api/tasks or PATCH /api/tasks/:id) instead of writing work/*.md directly`);
+    }
+    tasks.sort((a, b) => {
+        const s = statusRank(a.status) - statusRank(b.status);
+        if (s !== 0)
+            return s;
+        const p = priorityRank(a.priority) - priorityRank(b.priority);
+        if (p !== 0)
+            return p;
+        return a.id.localeCompare(b.id);
+    });
+    const counts = Object.fromEntries(STATUSES.map((s) => [s, 0]));
+    for (const t of tasks)
+        counts[t.status]++;
+    return {
+        version: INDEX_VERSION,
+        generatedAt: new Date().toISOString(),
+        root: config.root,
+        taskCount: tasks.length,
+        tasks,
+        counts,
+    };
+}
+/**
+ * Async counterpart of `buildIndex`. Identical result, but the per-task git
+ * enrichment (last commit + worktree status) runs CONCURRENTLY instead of one
+ * task at a time on the main thread — `buildIndex`'s synchronous git spawns
+ * each block the event loop for a full OS round-trip, so N tasks cost N
+ * serial round-trips no matter how idle the machine is. With 260+ tasks that
+ * was several seconds of RepoOS's slow boot on top of the redundant spawns
+ * fixed above (#0271 follow-up). Used by the server's startup path, which can
+ * let `listen()` proceed while this populates the index in the background;
+ * `buildIndex` remains for callers (the CLI) that want a synchronous result.
+ *
+ * `opts.fastWorktreeStatus` skips the per-worktree `git status` entirely and
+ * reports each task's `dirty` from the persisted cache plus its ahead count.
+ * The server passes this at boot and follows up with
+ * `LiveIndex.reconcileWorktreeStatus()` a moment later, trading a few seconds
+ * of a possibly-stale "uncommitted changes" dot for a fast first paint.
+ */
+export async function buildIndexAsync(config, opts = {}) {
+    const workPath = join(config.root, config.workDir);
+    const files = walkFiles(workPath, config.taskExtensions);
+    const useGit = isGitRepo(config.root);
+    const branches = useGit ? localBranches(config.root) : new Set();
+    const worktrees = useGit ? worktreePaths(config.root) : new Map();
+    const baseBranch = useGit ? currentBranch(config.root) : null;
+    const lastCommits = useGit
+        ? await lastCommitsForDirAsync(config.root, config.workDir)
+        : new Map();
+    let skippedTaskFiles = 0;
+    const tasks = [];
+    for (const absPath of files) {
+        const content = readFileSync(absPath, "utf8");
+        const { data } = parseDocument(content);
+        if (!("id" in data)) {
+            skippedTaskFiles++;
+            continue;
+        }
+        tasks.push(parseTask({
+            content,
+            absPath,
+            root: config.root,
+            defaultStatus: config.defaultStatus,
+            defaultAssignee: config.defaultAssignee,
+            git: emptyGitInfo(),
+        }));
+    }
+    if (skippedTaskFiles > 0) {
+        console.warn(`[repoos] skipped ${skippedTaskFiles} task file(s) with no \`id\` in frontmatter — ` +
+            `use the API (POST /api/tasks or PATCH /api/tasks/:id) instead of writing work/*.md directly`);
+    }
+    if (useGit) {
+        // Batched worktree status: two git spawns for every branch's ahead count
+        // and worktree HEAD, then one `git status` only per worktree whose HEAD
+        // moved since the last run (persisted in worktree-status.json). On a
+        // server reload — HEADs unchanged — this does zero `git status` calls;
+        // the old path ran two spawns per task branch (~2.5s at 40 branches).
+        const dirtyCache = readWorktreeDirtyCache(config);
+        const branchesWithTasks = tasks.map((t) => t.branch).filter((b) => !!b);
+        const { statuses, cache, changed } = await resolveWorktreeStatuses(config.root, branchesWithTasks, { baseBranch, cache: dirtyCache, skipStatus: opts.fastWorktreeStatus });
+        if (changed)
+            writeWorktreeDirtyCache(config, cache);
+        for (const base of tasks) {
+            const { subject, date } = lastCommits.get(base.path) ?? {
+                subject: null,
+                date: null,
+            };
+            const wt = (base.branch && statuses.get(base.branch)) || { path: null, dirty: false };
+            base.git = {
+                branchExists: base.branch ? branches.has(base.branch) : false,
+                worktreeExists: base.branch ? worktrees.has(base.branch) : false,
+                lastCommit: subject,
+                lastCommitAt: date,
+                worktreePath: wt.path,
+                dirty: wt.dirty,
+            };
+        }
+    }
+    tasks.sort((a, b) => {
+        const s = statusRank(a.status) - statusRank(b.status);
+        if (s !== 0)
+            return s;
+        const p = priorityRank(a.priority) - priorityRank(b.priority);
+        if (p !== 0)
+            return p;
+        return a.id.localeCompare(b.id);
+    });
+    const counts = Object.fromEntries(STATUSES.map((s) => [s, 0]));
+    for (const t of tasks)
+        counts[t.status]++;
+    return {
+        version: INDEX_VERSION,
+        generatedAt: new Date().toISOString(),
+        root: config.root,
+        taskCount: tasks.length,
+        tasks,
+        counts,
+    };
+}
+export function indexCachePath(config) {
+    return join(config.root, config.cacheDir, "index.json");
+}
+function worktreeDirtyCachePath(config) {
+    return join(config.root, config.cacheDir, "worktree-status.json");
+}
+/**
+ * Load the persisted per-branch working-tree dirtiness so a rebuild can skip
+ * `git status` for worktrees whose HEAD has not moved. Always safe: a missing,
+ * malformed, or stale file just means more `git status` calls this run.
+ */
+export function readWorktreeDirtyCache(config) {
+    const cache = new Map();
+    try {
+        const raw = JSON.parse(readFileSync(worktreeDirtyCachePath(config), "utf8"));
+        if (raw?.version === 1 && raw.branches) {
+            for (const [branch, v] of Object.entries(raw.branches)) {
+                if (v && typeof v.head === "string" && typeof v.uncommitted === "boolean") {
+                    cache.set(branch, { head: v.head, uncommitted: v.uncommitted });
+                }
+            }
+        }
+    }
+    catch {
+        /* no cache / bad cache -> empty */
+    }
+    return cache;
+}
+export function writeWorktreeDirtyCache(config, cache) {
+    const dir = join(config.root, config.cacheDir);
+    try {
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        const branches = {};
+        for (const [branch, v] of cache)
+            branches[branch] = { ...v };
+        writeFileSync(worktreeDirtyCachePath(config), JSON.stringify({ version: 1, branches }));
+    }
+    catch {
+        /* best-effort: losing the cache only costs `git status` calls next run */
+    }
+}
+export function writeIndexCache(config, index) {
+    const dir = join(config.root, config.cacheDir);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    // Strip absPath/body from the cache to keep it small and portable; callers
+    // that need them should read the file or rebuild in-memory.
+    const slim = {
+        ...index,
+        tasks: index.tasks.map((t) => ({ ...t, body: "", absPath: "" })),
+    };
+    writeFileSync(indexCachePath(config), JSON.stringify(slim, null, 2));
+}
+export function readIndexCache(config) {
+    const p = indexCachePath(config);
+    if (!existsSync(p))
+        return null;
+    try {
+        return JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/input.d.ts

@@ -0,0 +1,66 @@
+import type { RepoOSConfig } from "./types.js";
+export type InputStatus = "new" | "reviewing" | "processed";
+/**
+ * How a `processed` input was resolved: `task` means it became a task (the id
+ * is in `resolvedTask`), `none` means the decision was to take no action. An
+ * empty string means no resolution was recorded (e.g. an input moved to
+ * `processed` by hand before this feature existed).
+ */
+export type InputResolution = "task" | "none";
+export interface InputAttachment {
+    name: string;
+    mime: string;
+    size: number;
+    path: string;
+}
+export interface Input {
+    id: string;
+    /**
+     * Stable, zero-padded 4-digit number (`"0001"`), the input's counterpart to
+     * a task's `id`. Assigned once — at creation, or retroactively by
+     * `ensureInputNumbers` — and never reused or renumbered. Empty string only
+     * for an input written before this field existed and not yet migrated.
+     */
+    number: string;
+    title: string;
+    status: InputStatus;
+    body: string;
+    type: string;
+    area: string;
+    createdBy: string;
+    createdAt: string;
+    updatedAt: string;
+    path: string;
+    attachments: InputAttachment[];
+    resolution: InputResolution | "";
+    resolvedTask: string;
+}
+/**
+ * Retroactively assign a stable number to every input that lacks one, in
+ * place. Idempotent: numbers already present are never touched, renumbered, or
+ * reused, so a restart (or a repeated call) is a no-op. Existing inputs are
+ * numbered oldest-first (by `created_at`, then path) so the assignment is
+ * deterministic. Returns the inputs that were changed, for callers that want
+ * to commit them; an empty array means everything already had a number.
+ * See AGENTS.md — this touches the repo's own `inputs/*.md` data.
+ */
+export declare function ensureInputNumbers(c: RepoOSConfig): Input[];
+export declare function listInputs(c: RepoOSConfig): Input[];
+export declare function createInput(c: RepoOSConfig, body: string, type?: string, createdBy?: string): Input;
+export declare function updateInput(c: RepoOSConfig, id: string, status: InputStatus): Input;
+/**
+ * Record how an input was resolved and move it to `processed`. `task` stores
+ * the created task's id in `resolved_task`; `none` clears it. Both keys are
+ * persisted in the input file so the outcome survives a reload.
+ */
+export declare function resolveInput(c: RepoOSConfig, id: string, resolution: InputResolution, taskId?: string): Input;
+export declare function enrichInput(c: RepoOSConfig, id: string, fields: {
+    title?: string;
+    type?: string;
+    area?: string;
+}): Input;
+export declare function saveInputAttachment(c: RepoOSConfig, id: string, name: string, data: string): InputAttachment;
+export declare function readInputAttachment(c: RepoOSConfig, id: string, name: string): {
+    data: Buffer;
+    mime: string;
+};

package/dist/core/input.js

@@ -0,0 +1,222 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { parseDocument } from "./frontmatter.js";
+const q = (v) => `"${v.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+/**
+ * Set a frontmatter key in a file's raw content, adding it to the block if it
+ * isn't there yet. Assumes the content's frontmatter is the first `---` block
+ * (true for every input file `createInput` writes).
+ */
+function setField(content, key, value) {
+    const line = `${key}: ${q(value)}`;
+    const re = new RegExp(`^${key}:.*$`, "m");
+    return re.test(content) ? content.replace(re, line) : content.replace("---\n", `---\n${line}\n`);
+}
+const slug = (v) => v
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 55) || "input";
+const inputRoot = (c) => c.inputsDir ?? "inputs";
+const dir = (c) => join(c.root, inputRoot(c));
+const attDir = (c, id) => join(dir(c), ".attachments", id);
+/**
+ * Normalize a raw frontmatter `number` to the canonical zero-padded form.
+ * Returns `""` for anything that isn't a plain integer (missing, empty, or
+ * garbage), which callers treat as "needs a number".
+ */
+function normalizeNumber(v) {
+    if (typeof v === "number" && Number.isFinite(v))
+        return String(Math.trunc(v)).padStart(4, "0");
+    if (typeof v === "string" && /^\d+$/.test(v.trim()))
+        return v.trim().padStart(4, "0");
+    return "";
+}
+/** Next free 4-digit input number: highest existing number + 1, else `"0001"`. */
+function nextInputNumber(c) {
+    let max = 0;
+    for (const i of listInputs(c)) {
+        const n = parseInt(i.number, 10);
+        if (!Number.isNaN(n) && n > max)
+            max = n;
+    }
+    return String(max + 1).padStart(4, "0");
+}
+/**
+ * Retroactively assign a stable number to every input that lacks one, in
+ * place. Idempotent: numbers already present are never touched, renumbered, or
+ * reused, so a restart (or a repeated call) is a no-op. Existing inputs are
+ * numbered oldest-first (by `created_at`, then path) so the assignment is
+ * deterministic. Returns the inputs that were changed, for callers that want
+ * to commit them; an empty array means everything already had a number.
+ * See AGENTS.md — this touches the repo's own `inputs/*.md` data.
+ */
+export function ensureInputNumbers(c) {
+    const items = listInputs(c);
+    const missing = items
+        .filter((i) => !i.number)
+        .sort((a, b) => (a.createdAt || "").localeCompare(b.createdAt || "") || a.path.localeCompare(b.path));
+    if (!missing.length)
+        return [];
+    const used = new Set(items.map((i) => i.number).filter(Boolean));
+    let max = 0;
+    for (const n of used)
+        max = Math.max(max, parseInt(n, 10));
+    const changed = [];
+    for (const item of missing) {
+        let number = String(max + 1).padStart(4, "0");
+        while (used.has(number))
+            number = String(++max).padStart(4, "0");
+        used.add(number);
+        max = parseInt(number, 10);
+        const file = join(c.root, item.path);
+        writeFileSync(file, setField(readFileSync(file, "utf8"), "number", number));
+        changed.push({ ...item, number });
+    }
+    return changed;
+}
+export function listInputs(c) {
+    if (!existsSync(dir(c)))
+        return [];
+    return readdirSync(dir(c))
+        .filter((n) => n.endsWith(".md"))
+        .flatMap((name) => {
+        const path = join(inputRoot(c), name), parsed = parseDocument(readFileSync(join(dir(c), name), "utf8")), d = parsed.data;
+        if (typeof d.id !== "string")
+            return [];
+        const ad = attDir(c, d.id), attachments = existsSync(ad)
+            ? readdirSync(ad).map((n) => ({
+                name: n,
+                mime: mimeForName(n),
+                size: statSync(join(ad, n)).size,
+                path: join(inputRoot(c), ".attachments", d.id, n),
+            }))
+            : [];
+        return [
+            {
+                id: d.id,
+                number: normalizeNumber(d.number),
+                title: String(d.title ?? "Untitled input"),
+                status: (d.status === "reviewing" || d.status === "processed"
+                    ? d.status
+                    : "new"),
+                type: String(d.type ?? "other"),
+                area: String(d.area ?? ""),
+                createdBy: String(d.created_by ?? ""),
+                createdAt: String(d.created_at ?? ""),
+                updatedAt: String(d.updated_at ?? ""),
+                path,
+                body: parsed.body.trim(),
+                attachments,
+                resolution: (d.resolution === "task" || d.resolution === "none" ? d.resolution : ""),
+                resolvedTask: typeof d.resolved_task === "string" ? d.resolved_task : "",
+            },
+        ];
+    })
+        .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+export function createInput(c, body, type = "other", createdBy = "") {
+    const now = new Date().toISOString(), id = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 7)}`, number = nextInputNumber(c), title = body.trim().split(/\n/)[0].replace(/^#\s*/, "").slice(0, 100) || "Untitled input", name = `${id}-${slug(title)}.md`;
+    mkdirSync(dir(c), { recursive: true });
+    writeFileSync(join(dir(c), name), [
+        "---",
+        `id: ${q(id)}`,
+        `number: ${q(number)}`,
+        `title: ${q(title)}`,
+        "status: new",
+        `type: ${q(type)}`,
+        `created_by: ${q(createdBy)}`,
+        `created_at: ${q(now)}`,
+        `updated_at: ${q(now)}`,
+        "---",
+        "",
+        body.trim(),
+        "",
+    ].join("\n"));
+    return listInputs(c).find((i) => i.id === id);
+}
+export function updateInput(c, id, status) {
+    const item = listInputs(c).find((i) => i.id === id);
+    if (!item)
+        throw new Error("input not found");
+    const file = join(c.root, item.path);
+    let content = readFileSync(file, "utf8")
+        .replace(/^status:.*$/m, `status: ${status}`)
+        .replace(/^updated_at:.*$/m, `updated_at: ${q(new Date().toISOString())}`);
+    // A manual move out of `processed` invalidates any recorded resolution —
+    // leaving it behind would re-display a stale outcome if the input is later
+    // marked processed again without a real resolve action.
+    if (status !== "processed") {
+        content = setField(content, "resolution", "");
+        content = setField(content, "resolved_task", "");
+    }
+    writeFileSync(file, content);
+    return listInputs(c).find((i) => i.id === id);
+}
+/**
+ * Record how an input was resolved and move it to `processed`. `task` stores
+ * the created task's id in `resolved_task`; `none` clears it. Both keys are
+ * persisted in the input file so the outcome survives a reload.
+ */
+export function resolveInput(c, id, resolution, taskId = "") {
+    const item = listInputs(c).find((i) => i.id === id);
+    if (!item)
+        throw new Error("input not found");
+    const file = join(c.root, item.path);
+    let content = readFileSync(file, "utf8");
+    content = setField(content, "status", "processed");
+    content = setField(content, "resolution", resolution);
+    content = setField(content, "resolved_task", resolution === "task" ? taskId : "");
+    content = content.replace(/^updated_at:.*$/m, `updated_at: ${q(new Date().toISOString())}`);
+    writeFileSync(file, content);
+    return listInputs(c).find((i) => i.id === id);
+}
+export function enrichInput(c, id, fields) {
+    const item = listInputs(c).find((i) => i.id === id);
+    if (!item)
+        throw new Error("input not found");
+    const file = join(c.root, item.path);
+    let content = readFileSync(file, "utf8");
+    for (const [key, value] of Object.entries(fields))
+        if (typeof value === "string" && value.trim()) {
+            content = setField(content, key, value.trim());
+        }
+    content = content.replace(/^updated_at:.*$/m, `updated_at: ${q(new Date().toISOString())}`);
+    writeFileSync(file, content);
+    return listInputs(c).find((i) => i.id === id);
+}
+export function saveInputAttachment(c, id, name, data) {
+    if (!listInputs(c).some((i) => i.id === id))
+        throw new Error("input not found");
+    const safe = name.replace(/[^a-zA-Z0-9._-]/g, "-") || "attachment", target = join(attDir(c, id), safe);
+    mkdirSync(attDir(c, id), { recursive: true });
+    writeFileSync(target, Buffer.from(data, "base64"));
+    return {
+        name: safe,
+        mime: mimeForName(safe),
+        size: Buffer.byteLength(data, "base64"),
+        path: join(inputRoot(c), ".attachments", id, safe),
+    };
+}
+function mimeForName(name) {
+    const ext = name.toLowerCase().split(".").pop();
+    return ({
+        png: "image/png",
+        jpg: "image/jpeg",
+        jpeg: "image/jpeg",
+        gif: "image/gif",
+        webp: "image/webp",
+        svg: "image/svg+xml",
+        pdf: "application/pdf",
+        txt: "text/plain",
+        md: "text/markdown",
+    }[ext ?? ""] ?? "application/octet-stream");
+}
+export function readInputAttachment(c, id, name) {
+    if (!/^[a-zA-Z0-9._-]+$/.test(name) || !listInputs(c).some((i) => i.id === id))
+        throw new Error("attachment not found");
+    const base = resolve(attDir(c, id)), file = resolve(join(base, name));
+    if (!file.startsWith(`${base}/`) || !existsSync(file))
+        throw new Error("attachment not found");
+    return { data: readFileSync(file), mime: mimeForName(name) };
+}

package/dist/core/logger.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Centralized logging for RepoOS system, tasks, and agents.
+ * Logs are stored as newline-delimited JSON (NDJSON) in .repoos/logs/
+ * Structure:
+ *   .repoos/logs/system.log       - System-wide errors and critical events
+ *   .repoos/logs/tasks/<id>.log   - Per-task lifecycle and state changes
+ *   .repoos/logs/agents/<id>.log  - Per-agent activity and errors
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error" | "fatal";
+export interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    component: "system" | "task" | "agent" | "integration";
+    message: string;
+    context?: Record<string, unknown>;
+}
+interface LoggerOptions {
+    root: string;
+}
+/**
+ * Central logger for RepoOS. Creates and manages log files in .repoos/logs/
+ */
+export declare class Logger {
+    private root;
+    private logsDir;
+    constructor(opts: LoggerOptions);
+    /**
+     * Log a system-wide event or error. Includes fatal crashes and critical failures.
+     */
+    system(level: LogLevel, message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log a task lifecycle event: state changes, errors, transitions through pipeline.
+     */
+    task(taskId: string, level: LogLevel, message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log agent activity: startup, completion, errors, output streams.
+     */
+    agent(agentId: string, level: LogLevel, message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log integration/merge job activity (phase transitions, errors).
+     */
+    integration(taskId: string, level: LogLevel, message: string, context?: Record<string, unknown>): void;
+    /**
+     * Read up to `limit` log entries for a specific task or agent, in
+     * chronological order (oldest first). Callers that want most-recent-first
+     * (`getTaskLogs`, `getAgentLogs`, `getSystemLogs`) reverse the result.
+     */
+    readLogs(logPath: string, limit?: number): LogEntry[];
+    /**
+     * Get task logs in reverse order (most recent first).
+     */
+    getTaskLogs(taskId: string, limit?: number): LogEntry[];
+    /**
+     * Get agent logs in reverse order (most recent first).
+     */
+    getAgentLogs(agentId: string, limit?: number): LogEntry[];
+    /**
+     * Get system logs in reverse order (most recent first).
+     */
+    getSystemLogs(limit?: number): LogEntry[];
+    /**
+     * Write a log entry as NDJSON to the appropriate log file.
+     */
+    private write;
+}
+/**
+ * Create a logger for a repository root.
+ */
+export declare function createLogger(root: string): Logger;
+export {};