@scira/cli 0.1.2 → 0.1.3

package/dist/agent/tools.js

@@ -1,7 +1,7 @@
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
 import { readFile, writeFile, mkdir } from "node:fs/promises";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { dirname, join, relative } from "node:path";
 import { tool } from "ai";
 import { z } from "zod";
 import { multiSearchWeb } from "../tools/search-web.js";
@@ -11,6 +11,9 @@ import { logEvent } from "../storage/run-store.js";
 import { diffLines } from "diff";
 import { SKILL_NAMES, getSkill } from "./skills.js";
 import { createFileTools } from "../tools/file-tools.js";
+import { createTodoTool } from "./todos.js";
+import { resolveToolPath, resolveInsideWorkspace } from "./workspace.js";
+export { resolveInsideRun } from "./workspace.js";
 const execAsync = promisify(exec);
 const MAX_OUTPUT = 8000;
 function truncate(text, max = MAX_OUTPUT) {
@@ -22,18 +25,7 @@ function truncate(text, max = MAX_OUTPUT) {
 function snapshotSlug(url) {
     return url.replace(/^https?:\/\//u, "").replace(/[^a-zA-Z0-9]+/gu, "-").replace(/^-+|-+$/gu, "").slice(0, 80) || "page";
 }
-/**
- * Resolve a model-provided path against the run directory and refuse to escape it.
- */
-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 createResearchTools(runPath, config, onApprovalRequired) {
+export function createResearchTools(runPath, config, onApprovalRequired, workspacePath) {
     /** Gate a tool behind user approval unless approvalMode is "auto". */
     async function gate(toolName, description) {
         if (config.approvalMode === "auto" || !onApprovalRequired)
@@ -41,55 +33,60 @@ export function createResearchTools(runPath, config, onApprovalRequired) {
         return onApprovalRequired(toolName, description);
     }
     const claimsPath = join(runPath, "claims.jsonl");
-    return {
-        bash: tool({
-            description: "Run a shell command inside the run directory. Use for listing files, grepping notes, running scripts, git, etc. Returns combined stdout/stderr.",
-            inputSchema: z.object({
-                command: z.string().describe("The shell command to execute."),
-                timeoutMs: z.number().int().positive().max(120000).optional().describe("Optional timeout in ms (default 60000).")
-            }),
-            execute: async ({ command, timeoutMs }) => {
-                if (!await gate("bash", command))
-                    return "Command rejected by user.";
-                // Block commands that attempt to leave the run directory.
-                const escapesRunDir = /(?:^|[;&|`\n])\s*cd\s+[^.]/u.test(command)
-                    || /\.\.\/\.\.\//u.test(command)
-                    || /~[/\\]/u.test(command)
-                    || /\$HOME/u.test(command);
-                if (escapesRunDir) {
-                    return "Command rejected: navigating outside the run directory is not allowed.";
-                }
-                await logEvent(runPath, "tool.bash", { command });
-                try {
-                    const { stdout, stderr } = await execAsync(command, {
-                        cwd: runPath,
-                        timeout: timeoutMs ?? 60000,
-                        maxBuffer: 10 * 1024 * 1024,
-                        shell: "/bin/bash"
-                    });
-                    const out = [stdout, stderr].filter(Boolean).join("\n").trim();
-                    return truncate(out || "(no output)");
-                }
-                catch (error) {
-                    const err = error;
-                    const out = [err.stdout, err.stderr, err.message].filter(Boolean).join("\n").trim();
-                    return truncate(`Command failed:\n${out}`);
-                }
-            }
+    const filePathHint = workspacePath
+        ? "Project source paths (src/foo.ts, package.json, …) are relative to the project root. Harness files (plan.md, notes.md, report.md, sources.jsonl) live in the run directory — use those bare names."
+        : "Paths are relative to the run directory.";
+    const runBash = tool({
+        description: "Run a shell command inside the run directory. Use for listing files, grepping notes, running scripts, git, etc. Returns combined stdout/stderr.",
+        inputSchema: z.object({
+            command: z.string().describe("The shell command to execute."),
+            timeoutMs: z.number().int().positive().max(120000).optional().describe("Optional timeout in ms (default 60000).")
         }),
+        execute: async ({ command, timeoutMs }) => {
+            if (!await gate("bash", command))
+                return "Command rejected by user.";
+            const escapesRunDir = /(?:^|[;&|`\n])\s*cd\s+[^.]/u.test(command)
+                || /\.\.\/\.\.\//u.test(command)
+                || /~[/\\]/u.test(command)
+                || /\$HOME/u.test(command);
+            if (escapesRunDir) {
+                return "Command rejected: navigating outside the run directory is not allowed.";
+            }
+            await logEvent(runPath, "tool.bash", { command });
+            try {
+                const { stdout, stderr } = await execAsync(command, {
+                    cwd: runPath,
+                    timeout: timeoutMs ?? 60000,
+                    maxBuffer: 10 * 1024 * 1024,
+                    shell: "/bin/bash"
+                });
+                const out = [stdout, stderr].filter(Boolean).join("\n").trim();
+                return truncate(out || "(no output)");
+            }
+            catch (error) {
+                const err = error;
+                const out = [err.stdout, err.stderr, err.message].filter(Boolean).join("\n").trim();
+                return truncate(`Command failed:\n${out}`);
+            }
+        }
+    });
+    return {
+        ...(workspacePath ? {} : { bash: runBash }),
         writeFile: tool({
-            description: "Create or overwrite a file inside the run directory (e.g. plan.md, notes.md, report.md, sources.jsonl). Paths are relative to the run directory.",
+            description: `Create or overwrite a file. ${filePathHint}`,
             inputSchema: z.object({
-                path: z.string().describe("File path relative to the run directory."),
+                path: z.string().describe("File path."),
                 content: z.string().describe("Full file content to write.")
             }),
             execute: async ({ path, content }) => {
-                const isPlanOrReport = path === "plan.md" || path === "report.md";
-                if (isPlanOrReport) {
+                const resolved = resolveToolPath(runPath, workspacePath, path);
+                const needsApproval = resolved.scope === "workspace"
+                    || path === "plan.md"
+                    || path === "report.md";
+                if (needsApproval) {
                     let description;
-                    if (path === "report.md") {
-                        const abs = resolveInsideRun(runPath, path);
-                        const existing = await readFile(abs, "utf8").catch(() => "");
+                    if (path === "report.md" && resolved.scope === "run") {
+                        const existing = await readFile(resolved.abs, "utf8").catch(() => "");
                         const parts = diffLines(existing, content);
                         const added = parts.filter((p) => p.added).reduce((n, p) => n + (p.count ?? 0), 0);
                         const removed = parts.filter((p) => p.removed).reduce((n, p) => n + (p.count ?? 0), 0);
@@ -100,40 +97,55 @@ export function createResearchTools(runPath, config, onApprovalRequired) {
                             .join("\n");
                         description = `report.md  (+${added} / -${removed} lines)\n\n${diffPreview}`;
                     }
+                    else if (resolved.scope === "workspace") {
+                        const preview = content.length > 800 ? `${content.slice(0, 800)}\n…[${content.length} total chars]` : content;
+                        description = `Write to ${resolved.displayPath}:\n\n${preview}`;
+                    }
                     else {
                         description = `${path}\n\n${content.length > 600 ? `${content.slice(0, 600)}\n…` : content}`;
                     }
                     if (!await gate("writeFile", description))
-                        return `Write to ${path} rejected by user.`;
+                        return `Write to ${resolved.displayPath} rejected by user.`;
                 }
-                const abs = resolveInsideRun(runPath, path);
-                await mkdir(dirname(abs), { recursive: true });
-                await writeFile(abs, content);
+                await mkdir(dirname(resolved.abs), { recursive: true });
+                await writeFile(resolved.abs, content);
                 const eventType = path === "report.md" ? "report.updated" : path === "plan.md" ? "plan.updated" : "file.written";
-                await logEvent(runPath, eventType, { path, chars: content.length });
-                return `Wrote ${content.length} chars to ${path}`;
+                await logEvent(runPath, eventType, { path: resolved.displayPath, scope: resolved.scope, chars: content.length });
+                const where = resolved.scope === "workspace" ? "workspace" : "run";
+                return `Wrote ${content.length} chars to ${resolved.displayPath} (${where})`;
             }
         }),
         editFile: tool({
-            description: "Replace an exact string in an existing file inside the run directory. The oldString must match exactly and be unique.",
+            description: `Replace an exact string in an existing file. ${filePathHint} The oldString must match exactly and be unique.`,
             inputSchema: z.object({
-                path: z.string().describe("File path relative to the run directory."),
+                path: z.string().describe("File path."),
                 oldString: z.string().describe("Exact text to replace."),
                 newString: z.string().describe("Replacement text.")
             }),
             execute: async ({ path, oldString, newString }) => {
-                const abs = resolveInsideRun(runPath, path);
-                const current = await readFile(abs, "utf8");
+                const resolved = resolveToolPath(runPath, workspacePath, path);
+                const current = await readFile(resolved.abs, "utf8");
                 const occurrences = current.split(oldString).length - 1;
                 if (occurrences === 0) {
-                    return `No match for the given oldString in ${path}. No changes made.`;
+                    return `No match for the given oldString in ${resolved.displayPath}. No changes made.`;
                 }
                 if (occurrences > 1) {
-                    return `oldString matched ${occurrences} times in ${path}; provide more context to make it unique. No changes made.`;
+                    return `oldString matched ${occurrences} times in ${resolved.displayPath}; provide more context to make it unique. No changes made.`;
+                }
+                if (resolved.scope === "workspace") {
+                    const diff = diffLines(current, current.replace(oldString, newString));
+                    const preview = diff
+                        .filter((p) => p.added || p.removed)
+                        .flatMap((p) => p.value.split("\n").filter(Boolean).map((l) => `${p.added ? "+" : "-"} ${l}`))
+                        .slice(0, 15)
+                        .join("\n");
+                    if (!await gate("editFile", `Edit ${resolved.displayPath}:\n\n${preview}`)) {
+                        return `Edit to ${resolved.displayPath} rejected by user.`;
+                    }
                 }
-                await writeFile(abs, current.replace(oldString, newString));
-                await logEvent(runPath, "file.edited", { path });
-                return `Edited ${path}`;
+                await writeFile(resolved.abs, current.replace(oldString, newString));
+                await logEvent(runPath, "file.edited", { path: resolved.displayPath, scope: resolved.scope });
+                return `Edited ${resolved.displayPath}`;
             }
         }),
         createClaim: tool({
@@ -173,13 +185,13 @@ export function createResearchTools(runPath, config, onApprovalRequired) {
             }
         }),
         readFile: tool({
-            description: "Read a file inside the run directory.",
+            description: `Read a file. ${filePathHint}`,
             inputSchema: z.object({
-                path: z.string().describe("File path relative to the run directory.")
+                path: z.string().describe("File path.")
             }),
             execute: async ({ path }) => {
-                const abs = resolveInsideRun(runPath, path);
-                return truncate(await readFile(abs, "utf8"));
+                const resolved = resolveToolPath(runPath, workspacePath, path);
+                return truncate(await readFile(resolved.abs, "utf8"));
             }
         }),
         webSearch: tool({
@@ -246,6 +258,7 @@ export function createResearchTools(runPath, config, onApprovalRequired) {
                 return skill.content;
             }
         }),
+        todo: createTodoTool(runPath),
         ...(config.files ? createFileTools(runPath, config, onApprovalRequired) : {})
     };
 }
@@ -254,8 +267,9 @@ export function createResearchTools(runPath, config, onApprovalRequired) {
  * plus a single escalation tool the model can call (with user approval) to
  * switch into the full research harness.
  */
-export function createOneShotTools(runPath, config, onApprovalRequired, onEscalate) {
-    const all = createResearchTools(runPath, config, onApprovalRequired);
+export function createOneShotTools(runPath, config, onApprovalRequired, onEscalate, workspacePath, backgroundTasks) {
+    const all = createResearchTools(runPath, config, onApprovalRequired, workspacePath);
+    const coding = workspacePath ? createCodingTools(workspacePath, config, onApprovalRequired, backgroundTasks, runPath) : {};
     async function gate(toolName, description) {
         if (config.approvalMode === "auto" || !onApprovalRequired)
             return true;
@@ -264,6 +278,8 @@ export function createOneShotTools(runPath, config, onApprovalRequired, onEscala
     return {
         webSearch: all.webSearch,
         readUrl: all.readUrl,
+        todo: all.todo,
+        ...coding,
         requestFullResearch: tool({
             description: "Escalate from quick one-shot mode to the FULL research harness (skills, plan.md, claims, verification, sources.jsonl, report.md). " +
                 "You MUST call this if the user's goal involves research, deep dives, analysis, comparisons, history, or any topic that would benefit from structured multi-source research. " +
@@ -286,76 +302,18 @@ export function createOneShotTools(runPath, config, onApprovalRequired, onEscala
  * Workspace-aware tools for coding agent capabilities.
  * Unlike research tools, these operate on the full workspace, not just the run directory.
  */
-export function createCodingTools(workspacePath, config, onApprovalRequired) {
+export function createCodingTools(workspacePath, config, onApprovalRequired, backgroundTasks, runPath) {
     async function gate(toolName, description) {
         if (config.approvalMode === "auto" || !onApprovalRequired)
             return true;
         return onApprovalRequired(toolName, description);
     }
     function resolveWorkspacePath(candidate) {
-        return isAbsolute(candidate) ? candidate : resolve(workspacePath, candidate);
+        return resolveInsideWorkspace(workspacePath, candidate);
     }
     return {
-        readWorkspaceFile: tool({
-            description: "Read a file from the workspace. Use for examining code, configs, or any workspace file.",
-            inputSchema: z.object({
-                path: z.string().describe("File path (absolute or relative to workspace root).")
-            }),
-            execute: async ({ path }) => {
-                const abs = resolveWorkspacePath(path);
-                const content = await readFile(abs, "utf8");
-                return truncate(content);
-            }
-        }),
-        writeWorkspaceFile: tool({
-            description: "Create or overwrite a file in the workspace. Requires approval for safety.",
-            inputSchema: z.object({
-                path: z.string().describe("File path (absolute or relative to workspace root)."),
-                content: z.string().describe("Full file content to write.")
-            }),
-            execute: async ({ path, content }) => {
-                const abs = resolveWorkspacePath(path);
-                const preview = content.length > 800 ? `${content.slice(0, 800)}\n…[${content.length} total chars]` : content;
-                if (!await gate("writeWorkspaceFile", `Write to ${path}:\n\n${preview}`)) {
-                    return `Write to ${path} rejected by user.`;
-                }
-                await mkdir(dirname(abs), { recursive: true });
-                await writeFile(abs, content);
-                return `Wrote ${content.length} chars to ${path}`;
-            }
-        }),
-        editWorkspaceFile: tool({
-            description: "Replace an exact string in a workspace file. The oldString must match exactly and be unique.",
-            inputSchema: z.object({
-                path: z.string().describe("File path (absolute or relative to workspace root)."),
-                oldString: z.string().describe("Exact text to replace."),
-                newString: z.string().describe("Replacement text.")
-            }),
-            execute: async ({ path, oldString, newString }) => {
-                const abs = resolveWorkspacePath(path);
-                const current = await readFile(abs, "utf8");
-                const occurrences = current.split(oldString).length - 1;
-                if (occurrences === 0) {
-                    return `No match for the given oldString in ${path}. No changes made.`;
-                }
-                if (occurrences > 1) {
-                    return `oldString matched ${occurrences} times in ${path}; provide more context to make it unique. No changes made.`;
-                }
-                const diff = diffLines(current, current.replace(oldString, newString));
-                const preview = diff
-                    .filter((p) => p.added || p.removed)
-                    .flatMap((p) => p.value.split("\n").filter(Boolean).map((l) => `${p.added ? "+" : "-"} ${l}`))
-                    .slice(0, 15)
-                    .join("\n");
-                if (!await gate("editWorkspaceFile", `Edit ${path}:\n\n${preview}`)) {
-                    return `Edit to ${path} rejected by user.`;
-                }
-                await writeFile(abs, current.replace(oldString, newString));
-                return `Edited ${path}`;
-            }
-        }),
         listWorkspaceDir: tool({
-            description: "List files and directories in a workspace directory.",
+            description: "List files and directories in the project workspace.",
             inputSchema: z.object({
                 path: z.string().describe("Directory path (absolute or relative to workspace root)."),
                 recursive: z.boolean().optional().describe("Recursively list subdirectories (default false).")
@@ -396,18 +354,63 @@ export function createCodingTools(workspacePath, config, onApprovalRequired) {
                 }
             }
         }),
-        runWorkspaceCommand: tool({
-            description: "Execute a shell command in the workspace. Use for builds, tests, package installs, git, etc. Requires approval.",
+        bash: tool({
+            description: "Run shell commands in the workspace. " +
+                "Actions: run (foreground, default), background (start a long-running process like a dev server), list (show background tasks), output (read task logs), kill (stop a background task). " +
+                "Use background for servers and watchers; the task id and output remain available across turns.",
             inputSchema: z.object({
-                command: z.string().describe("The shell command to execute."),
+                action: z
+                    .enum(["run", "background", "list", "output", "kill"])
+                    .optional()
+                    .describe("run=foreground (default), background=spawn detached, list/output/kill manage background tasks."),
+                command: z.string().optional().describe("Shell command for run or background."),
+                taskId: z.string().optional().describe("Task id for output or kill."),
                 cwd: z.string().optional().describe("Working directory (default: workspace root)."),
-                timeoutMs: z.number().int().positive().max(300000).optional().describe("Timeout in ms (default 60000, max 300000).")
+                timeoutMs: z.number().int().positive().max(300000).optional().describe("Timeout for foreground run (default 60000)."),
+                tailLines: z.number().int().positive().max(200).optional().describe("Lines of output for action=output (default 50).")
             }),
-            execute: async ({ command, cwd, timeoutMs }) => {
+            execute: async ({ action, command, taskId, cwd, timeoutMs, tailLines }) => {
+                const act = action ?? "run";
                 const workDir = cwd ? resolveWorkspacePath(cwd) : workspacePath;
-                if (!await gate("runWorkspaceCommand", `Run command in ${relative(workspacePath, workDir) || "."}:\n\n${command}`)) {
+                if (act === "list") {
+                    if (!backgroundTasks)
+                        return "No background task manager available.";
+                    const tasks = await backgroundTasks.list();
+                    if (tasks.length === 0)
+                        return "No background tasks.";
+                    return tasks
+                        .map((t) => `${t.id} [${t.status}] pid=${t.pid} ${t.command}`)
+                        .join("\n");
+                }
+                if (act === "output") {
+                    if (!backgroundTasks)
+                        return "No background task manager available.";
+                    if (!taskId)
+                        return "output requires taskId.";
+                    return truncate(await backgroundTasks.getOutput(taskId, tailLines ?? 50));
+                }
+                if (act === "kill") {
+                    if (!backgroundTasks)
+                        return "No background task manager available.";
+                    if (!taskId)
+                        return "kill requires taskId.";
+                    return await backgroundTasks.kill(taskId);
+                }
+                if (!command)
+                    return `${act} requires command.`;
+                if (act === "background") {
+                    if (!backgroundTasks)
+                        return "Background tasks not available in this session.";
+                    const task = await backgroundTasks.spawn(command, workDir);
+                    if (runPath)
+                        await logEvent(runPath, "tool.bash.background", { taskId: task.id, command });
+                    return `Started background task ${task.id} (pid ${task.pid}): ${command}\nUse bash action=output taskId=${task.id} to read output.`;
+                }
+                if (!await gate("bash", `Run in ${relative(workspacePath, workDir) || "."}:\n\n${command}`)) {
                     return "Command rejected by user.";
                 }
+                if (runPath)
+                    await logEvent(runPath, "tool.bash", { command, cwd: workDir });
                 try {
                     const { stdout, stderr } = await execAsync(command, {
                         cwd: workDir,

package/dist/agent/tools.test.js

@@ -1,6 +1,9 @@
 import { describe, it, expect } from "vitest";
 import { resolveInsideRun } from "./tools.js";
+import { isRunArtifactPath, resolveProjectRoot, resolveToolPath } from "./workspace.js";
 const RUN = "/tmp/scira-test-run";
+const PROJECT = "/Users/me/my-app";
+const RUN_UNDER_SCIRA = `${PROJECT}/.scira/runs/2024-test-abc`;
 describe("resolveInsideRun", () => {
     it("resolves a relative path inside the run dir", () => {
         expect(resolveInsideRun(RUN, "notes.md")).toBe(`${RUN}/notes.md`);
@@ -25,3 +28,33 @@ describe("resolveInsideRun", () => {
         expect(() => resolveInsideRun(RUN, home)).toThrow("outside the run directory");
     });
 });
+describe("resolveProjectRoot", () => {
+    it("returns parent of .scira when run is under .scira/runs", () => {
+        expect(resolveProjectRoot(RUN_UNDER_SCIRA)).toBe(PROJECT);
+    });
+});
+describe("isRunArtifactPath", () => {
+    it("treats harness filenames as run artifacts", () => {
+        expect(isRunArtifactPath("plan.md")).toBe(true);
+        expect(isRunArtifactPath("notes.md")).toBe(true);
+        expect(isRunArtifactPath("src/foo.ts")).toBe(false);
+    });
+    it("treats run: prefix as run artifact", () => {
+        expect(isRunArtifactPath("run:custom.md")).toBe(true);
+    });
+});
+describe("resolveToolPath", () => {
+    it("routes source paths to workspace", () => {
+        const resolved = resolveToolPath(RUN_UNDER_SCIRA, PROJECT, "src/index.ts");
+        expect(resolved.scope).toBe("workspace");
+        expect(resolved.abs).toBe(`${PROJECT}/src/index.ts`);
+    });
+    it("routes plan.md to run directory", () => {
+        const resolved = resolveToolPath(RUN_UNDER_SCIRA, PROJECT, "plan.md");
+        expect(resolved.scope).toBe("run");
+        expect(resolved.abs).toBe(`${RUN_UNDER_SCIRA}/plan.md`);
+    });
+    it("blocks writes into .scira from workspace paths", () => {
+        expect(() => resolveToolPath(RUN_UNDER_SCIRA, PROJECT, ".scira/config.json")).toThrow("inside .scira");
+    });
+});

package/dist/agent/workspace.js

@@ -0,0 +1,85 @@
+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"
+]);
+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;
+    const base = normalized.split("/").pop() ?? normalized;
+    return RUN_ARTIFACT_FILES.has(base);
+}
+/**
+ * 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;
+}