@scira/cli 0.1.2 → 0.1.3

package/dist/tools/background-tasks.js

@@ -0,0 +1,261 @@
+import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+const MAX_OUTPUT_LINES = 500;
+const MAX_TAIL_CHARS = 4000;
+function nextTaskId(existing) {
+    const nums = existing
+        .map((t) => /^task_(\d+)$/u.exec(t.id)?.[1])
+        .filter((n) => Boolean(n))
+        .map((n) => Number.parseInt(n, 10));
+    const next = nums.length > 0 ? Math.max(...nums) + 1 : 1;
+    return `task_${String(next).padStart(3, "0")}`;
+}
+function tailText(lines, maxChars = MAX_TAIL_CHARS) {
+    const joined = lines.join("\n");
+    if (joined.length <= maxChars)
+        return joined;
+    return `…[truncated]\n${joined.slice(-maxChars)}`;
+}
+/** Returns true if a process with this pid is still running. */
+function isProcessRunning(pid) {
+    if (pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isValidRecord(t) {
+    if (typeof t !== "object" || t === null)
+        return false;
+    const r = t;
+    return typeof r.id === "string"
+        && typeof r.command === "string"
+        && typeof r.cwd === "string"
+        && typeof r.pid === "number"
+        && typeof r.startedAt === "string"
+        && typeof r.status === "string"
+        && (r.status === "running" || r.status === "exited" || r.status === "killed");
+}
+export class BackgroundTaskManager {
+    persistPath;
+    defaultCwd;
+    runtime = new Map();
+    records = [];
+    loaded = false;
+    sessionToken = randomUUID();
+    constructor(persistPath, defaultCwd) {
+        this.persistPath = persistPath;
+        this.defaultCwd = defaultCwd;
+    }
+    async ensureLoaded() {
+        if (this.loaded)
+            return;
+        this.loaded = true;
+        try {
+            const raw = await readFile(this.persistPath, "utf8");
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed)) {
+                this.records = parsed.filter(isValidRecord);
+            }
+        }
+        catch {
+            this.records = [];
+        }
+        this.reconcileStaleTasks();
+    }
+    /** Mark persisted "running" tasks as exited when no live process tracks them. */
+    reconcileStaleTasks() {
+        let changed = false;
+        for (const rec of this.records) {
+            if (rec.status !== "running")
+                continue;
+            if (this.runtime.has(rec.id))
+                continue;
+            if (rec.sessionToken && rec.sessionToken !== this.sessionToken) {
+                rec.status = "exited";
+                rec.exitCode ??= null;
+                changed = true;
+                continue;
+            }
+            if (rec.pid > 0 && isProcessRunning(rec.pid))
+                continue;
+            rec.status = "exited";
+            rec.exitCode ??= null;
+            changed = true;
+        }
+        if (changed)
+            void this.persist();
+    }
+    async persist() {
+        await mkdir(dirname(this.persistPath), { recursive: true });
+        await writeFile(this.persistPath, JSON.stringify(this.records, null, 2) + "\n");
+    }
+    syncRecord(task) {
+        const idx = this.records.findIndex((r) => r.id === task.record.id);
+        task.record.outputTail = tailText(task.output);
+        if (idx === -1)
+            this.records.push({ ...task.record });
+        else
+            this.records[idx] = { ...task.record };
+    }
+    async getTask(taskId) {
+        await this.ensureLoaded();
+        this.reconcileStaleTasks();
+        const live = this.runtime.get(taskId);
+        if (live)
+            return { ...live.record };
+        return this.records.find((r) => r.id === taskId);
+    }
+    async spawn(command, cwd) {
+        await this.ensureLoaded();
+        const id = nextTaskId(this.records);
+        const workDir = cwd ?? this.defaultCwd;
+        const proc = spawn(command, {
+            cwd: workDir,
+            shell: "/bin/bash",
+            env: process.env,
+            detached: false,
+            stdio: ["ignore", "pipe", "pipe"]
+        });
+        const record = {
+            id,
+            command,
+            cwd: workDir,
+            pid: proc.pid ?? 0,
+            startedAt: new Date().toISOString(),
+            status: "running",
+            exitCode: null,
+            outputTail: "",
+            sessionToken: this.sessionToken
+        };
+        const output = [];
+        let partial = "";
+        const append = (chunk) => {
+            const text = partial + chunk.toString();
+            const lines = text.split("\n");
+            partial = lines.pop() ?? "";
+            for (const line of lines) {
+                if (line.length > 0)
+                    output.push(line);
+            }
+            while (output.length > MAX_OUTPUT_LINES)
+                output.shift();
+            const rt = this.runtime.get(id);
+            if (rt) {
+                rt.output = output;
+                rt.record.outputTail = tailText(output);
+            }
+        };
+        const flushPartial = () => {
+            if (partial.length > 0) {
+                output.push(partial);
+                partial = "";
+                while (output.length > MAX_OUTPUT_LINES)
+                    output.shift();
+            }
+        };
+        proc.stdout?.on("data", append);
+        proc.stderr?.on("data", append);
+        const runtime = { record, proc, output };
+        this.runtime.set(id, runtime);
+        this.records.push({ ...record });
+        await this.persist();
+        proc.on("close", (code) => {
+            flushPartial();
+            if (runtime.killedByUser) {
+                record.status = "killed";
+                record.exitCode = record.exitCode ?? 143;
+            }
+            else {
+                record.status = "exited";
+                record.exitCode = code;
+            }
+            record.outputTail = tailText(output);
+            this.syncRecord(runtime);
+            void this.persist();
+            this.runtime.delete(id);
+        });
+        proc.on("error", (err) => {
+            flushPartial();
+            output.push(`[spawn error] ${err.message}`);
+            record.status = "exited";
+            record.exitCode = 1;
+            record.outputTail = tailText(output);
+            this.syncRecord(runtime);
+            void this.persist();
+            this.runtime.delete(id);
+        });
+        return { ...record };
+    }
+    async list() {
+        await this.ensureLoaded();
+        this.reconcileStaleTasks();
+        for (const rt of this.runtime.values()) {
+            rt.record.outputTail = tailText(rt.output);
+            this.syncRecord(rt);
+        }
+        return this.records.map((r) => {
+            const live = this.runtime.get(r.id);
+            return live ? { ...live.record } : { ...r };
+        });
+    }
+    async getOutput(taskId, tailLines = 50) {
+        await this.ensureLoaded();
+        this.reconcileStaleTasks();
+        const live = this.runtime.get(taskId);
+        if (live) {
+            const lines = live.output.slice(-tailLines);
+            return lines.length > 0 ? lines.join("\n") : "(no output yet)";
+        }
+        const rec = this.records.find((r) => r.id === taskId);
+        if (!rec)
+            return `Task "${taskId}" not found.`;
+        const lines = rec.outputTail.split("\n").slice(-tailLines);
+        return lines.length > 0 ? lines.join("\n") : "(no output)";
+    }
+    async kill(taskId) {
+        await this.ensureLoaded();
+        this.reconcileStaleTasks();
+        const live = this.runtime.get(taskId);
+        if (live) {
+            live.killedByUser = true;
+            live.proc.kill("SIGTERM");
+            live.record.status = "killed";
+            live.record.exitCode = live.record.exitCode ?? 143;
+            this.syncRecord(live);
+            await this.persist();
+            return `Killed ${taskId} (pid ${live.record.pid}).`;
+        }
+        const rec = this.records.find((r) => r.id === taskId);
+        if (!rec)
+            return `Task "${taskId}" not found.`;
+        if (rec.status !== "running")
+            return `${taskId} is already ${rec.status}.`;
+        if (rec.sessionToken !== this.sessionToken) {
+            rec.status = "exited";
+            await this.persist();
+            return `Task ${taskId} was started in a previous session and cannot be killed from here. Marked as exited.`;
+        }
+        rec.status = "exited";
+        rec.exitCode ??= null;
+        await this.persist();
+        return `Task ${taskId} is not running in this session.`;
+    }
+    async formatContextForAgent() {
+        const tasks = await this.list();
+        const active = tasks.filter((t) => t.status === "running");
+        if (active.length === 0)
+            return "";
+        const lines = active.map((t) => `  - ${t.id}: [running pid ${t.pid}] ${t.command} (cwd: ${t.cwd})`);
+        return `\nActive background tasks:\n${lines.join("\n")}\nUse bash with action "output" and taskId to read logs, or action "kill" to stop a task.\n`;
+    }
+}
+export function createBackgroundTaskManager(runPath, workspacePath) {
+    return new BackgroundTaskManager(join(runPath, "background-tasks.json"), workspacePath);
+}

package/dist/tools/bash-policy.test.js

@@ -0,0 +1,38 @@
+import { describe, it, expect } from "vitest";
+import { isReadOnlyBashCommand } from "./agent-tools.js";
+describe("isReadOnlyBashCommand", () => {
+    it("allows common read-only commands", () => {
+        expect(isReadOnlyBashCommand("ls -la")).toBe(true);
+        expect(isReadOnlyBashCommand("cat package.json")).toBe(true);
+        expect(isReadOnlyBashCommand("git status")).toBe(true);
+        expect(isReadOnlyBashCommand("git log --oneline -5")).toBe(true);
+        expect(isReadOnlyBashCommand("git branch")).toBe(false);
+        expect(isReadOnlyBashCommand("git remote -v")).toBe(false);
+    });
+    it("rejects chained or mutating commands", () => {
+        expect(isReadOnlyBashCommand("ls; rm -rf /")).toBe(false);
+        expect(isReadOnlyBashCommand("git commit -m x")).toBe(false);
+        expect(isReadOnlyBashCommand("npm install")).toBe(false);
+    });
+    it("rejects multiline chaining and destructive find", () => {
+        expect(isReadOnlyBashCommand("git status\nrm -rf .")).toBe(false);
+        expect(isReadOnlyBashCommand("git status\nnpm install")).toBe(false);
+        expect(isReadOnlyBashCommand("find . -delete")).toBe(false);
+        expect(isReadOnlyBashCommand("find . -exec rm {} +")).toBe(false);
+        expect(isReadOnlyBashCommand("find . -type f")).toBe(true);
+    });
+    it("rejects path traversal and absolute paths", () => {
+        expect(isReadOnlyBashCommand("cat ../secret")).toBe(false);
+        expect(isReadOnlyBashCommand("grep -r token ..")).toBe(false);
+        expect(isReadOnlyBashCommand("ls /")).toBe(false);
+        expect(isReadOnlyBashCommand("cat .//etc/passwd")).toBe(false);
+        expect(isReadOnlyBashCommand("grep -r secret .//etc")).toBe(false);
+        expect(isReadOnlyBashCommand("cat package.json")).toBe(true);
+        expect(isReadOnlyBashCommand("grep -rn foo .")).toBe(true);
+    });
+    it("rejects privileged flags on allowlisted binaries", () => {
+        expect(isReadOnlyBashCommand("git diff --extcmd=sh")).toBe(false);
+        expect(isReadOnlyBashCommand("rg --pre=bash -- foo .")).toBe(false);
+        expect(isReadOnlyBashCommand("git -c alias.status=!rm status")).toBe(false);
+    });
+});

package/dist/tools/file-tools.js

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { Files } from "files-sdk";
 import { fs } from "files-sdk/fs";
 import { logEvent } from "../storage/run-store.js";
+import { PLAN_MODE_MSG } from "./agent-tools.js";
 const MAX_CONTENT = 8000;
 function truncate(text, max = MAX_CONTENT) {
     if (text.length <= max)
@@ -18,7 +19,7 @@ async function takeAsync(iter, max) {
     }
     return results;
 }
-export function createFileTools(runPath, config, onApprovalRequired) {
+export function createFileTools(runPath, config, onApprovalRequired, getPlanMode) {
     const dir = config.files.dir;
     const files = new Files({ adapter: fs({ root: dir }) });
     async function gate(toolName, description) {
@@ -102,6 +103,8 @@ export function createFileTools(runPath, config, onApprovalRequired) {
                 destination: z.string().describe("Target file key.")
             }),
             execute: async ({ source, destination }) => {
+                if (getPlanMode?.())
+                    return PLAN_MODE_MSG;
                 if (!await gate("moveFile", `Move file:\n  ${source} → ${destination}`)) {
                     return "Move rejected by user.";
                 }
@@ -116,6 +119,8 @@ export function createFileTools(runPath, config, onApprovalRequired) {
                 key: z.string().describe("File key to delete.")
             }),
             execute: async ({ key }) => {
+                if (getPlanMode?.())
+                    return PLAN_MODE_MSG;
                 if (!await gate("deleteFile", `Delete file: "${key}"`)) {
                     return "Delete rejected by user.";
                 }

package/dist/tools/search-web.js

@@ -131,23 +131,41 @@ const STRATEGIES = {
     exa: exaSearch,
     firecrawl: firecrawlSearch
 };
+function formatSearchError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 export async function multiSearchWeb(queries, perQuery, config) {
     const provider = config.search.provider;
     const strategy = STRATEGIES[provider];
     const settled = await Promise.allSettled(queries.map((q, i) => strategy(q, config, perQuery[i] ?? {})));
-    const searches = await Promise.all(settled.map(async (res, i) => {
+    return Promise.all(settled.map(async (res, i) => {
+        let error;
+        if (res.status === "rejected") {
+            error = formatSearchError(res.reason);
+        }
         if (res.status === "fulfilled" && res.value.length > 0) {
             return { query: queries[i], results: res.value };
         }
-        // per-query fallback to Firecrawl
         if (provider !== "firecrawl" && hasEnv("FIRECRAWL_API_KEY")) {
             try {
                 const fallback = await firecrawlSearch(queries[i], config, perQuery[i] ?? {});
-                return { query: queries[i], results: fallback };
+                if (fallback.length > 0) {
+                    return { query: queries[i], results: fallback };
+                }
+                if (!error)
+                    error = "primary search returned no results; firecrawl fallback also returned no results";
+            }
+            catch (fallbackError) {
+                const fallbackMsg = formatSearchError(fallbackError);
+                error = error ? `${error}; firecrawl fallback failed: ${fallbackMsg}` : `firecrawl fallback failed: ${fallbackMsg}`;
             }
-            catch { /* ignore */ }
         }
-        return { query: queries[i], results: [] };
+        else if (res.status === "rejected" && provider !== "firecrawl" && !hasEnv("FIRECRAWL_API_KEY")) {
+            error = `${error} (set FIRECRAWL_API_KEY for automatic fallback)`;
+        }
+        else if (res.status === "fulfilled" && res.value.length === 0) {
+            error = error ?? "search returned no results";
+        }
+        return { query: queries[i], results: [], ...(error ? { error } : {}) };
     }));
-    return searches;
 }

package/dist/tools/search-web.test.js

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import { SciraConfigSchema } from "../types/index.js";
+import { multiSearchWeb } from "./search-web.js";
+const BASE_CONFIG = SciraConfigSchema.parse({});
+describe("multiSearchWeb", () => {
+    it("reports provider errors instead of silently returning empty results", async () => {
+        const origExa = process.env.EXA_API_KEY;
+        const origFc = process.env.FIRECRAWL_API_KEY;
+        process.env.EXA_API_KEY = "invalid";
+        process.env.FIRECRAWL_API_KEY = "invalid";
+        const config = { ...BASE_CONFIG, search: { ...BASE_CONFIG.search, provider: "exa" } };
+        const results = await multiSearchWeb(["test query"], [{}], config);
+        expect(results[0]?.results).toEqual([]);
+        expect(results[0]?.error).toMatch(/invalid|unauthorized|api key/i);
+        if (origExa)
+            process.env.EXA_API_KEY = origExa;
+        else
+            delete process.env.EXA_API_KEY;
+        if (origFc)
+            process.env.FIRECRAWL_API_KEY = origFc;
+        else
+            delete process.env.FIRECRAWL_API_KEY;
+    });
+});

package/dist/tools/todos.js

@@ -0,0 +1,140 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { tool } from "ai";
+import { z } from "zod";
+import { logEvent } from "../storage/run-store.js";
+const TodoStatusSchema = z.enum(["pending", "in_progress", "completed", "cancelled"]);
+function nextTodoId(existing) {
+    const nums = existing
+        .map((t) => /^todo_(\d+)$/u.exec(t.id)?.[1])
+        .filter((n) => Boolean(n))
+        .map((n) => Number.parseInt(n, 10));
+    const next = nums.length > 0 ? Math.max(...nums) + 1 : 1;
+    return `todo_${String(next).padStart(3, "0")}`;
+}
+async function loadTodos(path) {
+    try {
+        const raw = await readFile(path, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((t) => typeof t === "object" && t !== null && typeof t.id === "string");
+    }
+    catch {
+        return [];
+    }
+}
+async function saveTodos(path, items) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(items, null, 2) + "\n");
+}
+function formatTodoList(items) {
+    if (items.length === 0)
+        return "No todos.";
+    const icon = {
+        pending: "[ ]",
+        in_progress: "[~]",
+        completed: "[x]",
+        cancelled: "[-]"
+    };
+    return items
+        .map((t) => `${icon[t.status]} ${t.id}: ${t.content} (${t.status})`)
+        .join("\n");
+}
+export function createTodoTool(runPath) {
+    const todosPath = join(runPath, "todos.json");
+    return tool({
+        description: "Manage structured task todos for the current session. " +
+            "Actions: create (add items), edit (change content), mark (set status), remove (delete one), rewrite (replace entire list), list (show all). " +
+            "Statuses: pending, in_progress, completed, cancelled.",
+        inputSchema: z.object({
+            action: z.enum(["create", "edit", "mark", "remove", "rewrite", "list"]),
+            id: z.string().optional().describe("Todo id for edit, mark, or remove."),
+            content: z.string().optional().describe("Todo text for create, edit, or rewrite items."),
+            status: TodoStatusSchema.optional().describe("Status for mark action or rewrite items."),
+            items: z
+                .array(z.object({
+                id: z.string().optional(),
+                content: z.string(),
+                status: TodoStatusSchema.optional()
+            }))
+                .optional()
+                .describe("Items for create or rewrite.")
+        }),
+        execute: async ({ action, id, content, status, items }) => {
+            const now = new Date().toISOString();
+            let todos = await loadTodos(todosPath);
+            switch (action) {
+                case "list":
+                    return formatTodoList(todos);
+                case "create": {
+                    const toAdd = items ?? (content ? [{ content, status: status ?? "pending" }] : []);
+                    if (toAdd.length === 0)
+                        return "create requires content or items.";
+                    for (const item of toAdd) {
+                        const todoId = item.id ?? nextTodoId(todos);
+                        todos.push({
+                            id: todoId,
+                            content: item.content,
+                            status: item.status ?? "pending",
+                            createdAt: now,
+                            updatedAt: now
+                        });
+                    }
+                    await saveTodos(todosPath, todos);
+                    await logEvent(runPath, "todo.created", { count: toAdd.length });
+                    return `Created ${toAdd.length} todo(s).\n\n${formatTodoList(todos)}`;
+                }
+                case "edit": {
+                    if (!id || !content)
+                        return "edit requires id and content.";
+                    const idx = todos.findIndex((t) => t.id === id);
+                    if (idx === -1)
+                        return `Todo "${id}" not found.`;
+                    todos[idx] = { ...todos[idx], content, updatedAt: now };
+                    await saveTodos(todosPath, todos);
+                    await logEvent(runPath, "todo.edited", { id });
+                    return `Updated ${id}.\n\n${formatTodoList(todos)}`;
+                }
+                case "mark": {
+                    if (!id || !status)
+                        return "mark requires id and status.";
+                    const idx = todos.findIndex((t) => t.id === id);
+                    if (idx === -1)
+                        return `Todo "${id}" not found.`;
+                    todos[idx] = { ...todos[idx], status, updatedAt: now };
+                    await saveTodos(todosPath, todos);
+                    await logEvent(runPath, "todo.marked", { id, status });
+                    return `Marked ${id} as ${status}.\n\n${formatTodoList(todos)}`;
+                }
+                case "remove": {
+                    if (!id)
+                        return "remove requires id.";
+                    const before = todos.length;
+                    todos = todos.filter((t) => t.id !== id);
+                    if (todos.length === before)
+                        return `Todo "${id}" not found.`;
+                    await saveTodos(todosPath, todos);
+                    await logEvent(runPath, "todo.removed", { id });
+                    return `Removed ${id}.\n\n${formatTodoList(todos)}`;
+                }
+                case "rewrite": {
+                    if (!items || items.length === 0)
+                        return "rewrite requires a non-empty items array.";
+                    todos = items.map((item, i) => ({
+                        id: item.id ?? `todo_${String(i + 1).padStart(3, "0")}`,
+                        content: item.content,
+                        status: item.status ?? "pending",
+                        createdAt: now,
+                        updatedAt: now
+                    }));
+                    await saveTodos(todosPath, todos);
+                    await logEvent(runPath, "todo.rewritten", { count: todos.length });
+                    return `Rewrote todo list (${todos.length} items).\n\n${formatTodoList(todos)}`;
+                }
+                default:
+                    return `Unknown action: ${action}`;
+            }
+        }
+    });
+}

package/dist/tools/workspace.js

@@ -0,0 +1,91 @@
+import { isAbsolute, relative, resolve } from "node:path";
+/** Harness files that live under .scira/runs/<id>/, not in the project codebase. */
+export const RUN_ARTIFACT_FILES = new Set([
+    "plan.md",
+    "notes.md",
+    "report.md",
+    "sources.jsonl",
+    "claims.jsonl",
+    "goal.md",
+    "RESEARCH.md",
+    "scope.json",
+    "progress.md",
+    "handoff.md",
+    "convo.json",
+    "todos.json",
+    "background-tasks.json",
+    "title.md",
+    "run.log.jsonl"
+]);
+/** Normalize a run-scoped path to its harness basename (strips run: and ./ prefixes). */
+export function harnessBasename(displayPath) {
+    return displayPath.replace(/^run:/u, "").replace(/^\.\//u, "");
+}
+export function isRunArtifactPath(candidate) {
+    if (candidate.startsWith("run:"))
+        return true;
+    const normalized = candidate.replace(/\\/g, "/").replace(/^\.\//u, "");
+    if (normalized.startsWith("snapshots/") || normalized.startsWith("artifacts/"))
+        return true;
+    // Harness files are referenced by bare filename at the run root, not nested paths.
+    if (normalized.includes("/"))
+        return false;
+    return RUN_ARTIFACT_FILES.has(normalized);
+}
+/**
+ * Project root: parent of `.scira` when the run lives under `.scira/runs/…`,
+ * otherwise the current working directory (unless cwd is inside `.scira`).
+ */
+export function resolveProjectRoot(runPath, cwd = process.cwd()) {
+    const fromRun = projectRootFromPath(runPath);
+    if (fromRun)
+        return fromRun;
+    const fromCwd = projectRootFromPath(resolve(cwd));
+    if (fromCwd)
+        return fromCwd;
+    return resolve(cwd);
+}
+function projectRootFromPath(absPath) {
+    const normalized = resolve(absPath).replace(/\\/g, "/");
+    const marker = "/.scira/";
+    const idx = normalized.indexOf(marker);
+    if (idx >= 0)
+        return normalized.slice(0, idx) || "/";
+    if (normalized.endsWith("/.scira"))
+        return normalized.slice(0, -"/.scira".length) || "/";
+    return undefined;
+}
+export function resolveToolPath(runPath, workspacePath, candidate) {
+    const raw = candidate.trim();
+    if (raw.startsWith("run:")) {
+        const inner = raw.slice(4);
+        const abs = resolveInsideRun(runPath, inner);
+        return { abs, displayPath: inner, scope: "run" };
+    }
+    if (workspacePath && !isRunArtifactPath(raw)) {
+        const abs = resolveInsideWorkspace(workspacePath, raw);
+        return { abs, displayPath: raw, scope: "workspace" };
+    }
+    const abs = resolveInsideRun(runPath, raw);
+    return { abs, displayPath: raw, scope: "run" };
+}
+export function resolveInsideRun(runPath, candidate) {
+    const abs = isAbsolute(candidate) ? candidate : resolve(runPath, candidate);
+    const rel = relative(runPath, abs);
+    if (rel.startsWith("..") || isAbsolute(rel)) {
+        throw new Error(`Path "${candidate}" is outside the run directory and is not allowed.`);
+    }
+    return abs;
+}
+export function resolveInsideWorkspace(workspacePath, candidate) {
+    const abs = isAbsolute(candidate) ? candidate : resolve(workspacePath, candidate);
+    const rel = relative(workspacePath, abs);
+    if (rel.startsWith("..") || isAbsolute(rel)) {
+        throw new Error(`Path "${candidate}" is outside the project workspace.`);
+    }
+    const norm = rel.replace(/\\/g, "/");
+    if (norm === ".scira" || norm.startsWith(".scira/")) {
+        throw new Error(`Path "${candidate}" is inside .scira. Harness files use bare names (plan.md, notes.md, report.md). Source code paths are relative to the project root.`);
+    }
+    return abs;
+}