voratiq 0.1.0-beta.3 → 0.1.0-beta.4

package/dist/bin.js

@@ -16,6 +16,7 @@ import { createRunCommand } from "./cli/run.js";
 import { createSpecCommand } from "./cli/spec.js";
 import { terminateActiveRun } from "./commands/run/lifecycle.js";
 import { renderCliError } from "./render/utils/errors.js";
+import { flushAllReviewRecordBuffers } from "./reviews/records/persistence.js";
 import { flushAllRunRecordBuffers } from "./runs/records/persistence.js";
 import { flushAllSpecRecordBuffers } from "./specs/records/persistence.js";
 import { toErrorMessage } from "./utils/errors.js";
@@ -75,6 +76,12 @@ async function flushPendingHistory() {
     catch (error) {
         console.warn(`[voratiq] Failed to flush run history buffers: ${error.message}`);
     }
+    try {
+        await flushAllReviewRecordBuffers();
+    }
+    catch (error) {
+        console.warn(`[voratiq] Failed to flush review history buffers: ${error.message}`);
+    }
     try {
         await flushAllSpecRecordBuffers();
     }

package/dist/cli/review.d.ts

@@ -2,6 +2,7 @@ import { Command } from "commander";
 import { type ReviewCommandResult as ReviewExecutionResult } from "../commands/review/command.js";
 export interface ReviewCommandOptions {
     runId: string;
+    agentId?: string;
 }
 export interface ReviewCommandResult extends ReviewExecutionResult {
     body: string;

package/dist/cli/review.js

@@ -1,17 +1,43 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
 import { Command } from "commander";
+import { checkPlatformSupport } from "../agents/runtime/sandbox.js";
 import { executeReviewCommand, } from "../commands/review/command.js";
-import { resolveCliContext } from "../preflight/index.js";
+import { buildMarkdownPreviewLines } from "../commands/shared/preview.js";
+import { ensureSandboxDependencies, resolveCliContext, } from "../preflight/index.js";
 import { renderReviewTranscript } from "../render/transcripts/review.js";
 import { writeCommandOutput } from "./output.js";
 export async function runReviewCommand(options) {
-    const { runId } = options;
+    const { runId, agentId } = options;
     const { root, workspacePaths } = await resolveCliContext();
+    checkPlatformSupport();
+    ensureSandboxDependencies();
+    writeCommandOutput({
+        alerts: [{ severity: "info", message: "Generating review..." }],
+    });
     const execution = await executeReviewCommand({
         root,
         runsFilePath: workspacePaths.runsFile,
+        reviewsFilePath: workspacePaths.reviewsFile,
         runId,
+        agentId,
+    });
+    let previewLines;
+    try {
+        const reviewContent = await readFile(resolve(root, execution.outputPath), "utf8");
+        previewLines = buildMarkdownPreviewLines(reviewContent);
+    }
+    catch {
+        previewLines = undefined;
+    }
+    const body = renderReviewTranscript({
+        runId: execution.runRecord.runId,
+        outputPath: execution.outputPath,
+        previewLines,
+        ...(execution.missingArtifacts.length > 0
+            ? { missingArtifacts: execution.missingArtifacts }
+            : {}),
     });
-    const body = renderReviewTranscript(execution.runRecord);
     return {
         ...execution,
         body,
@@ -19,11 +45,15 @@ export async function runReviewCommand(options) {
 }
 export function createReviewCommand() {
     return new Command("review")
-        .description("Summarize artifacts from a completed run")
+        .description("Generate a one-shot, headless review of run artifacts")
         .requiredOption("--run <run-id>", "Identifier of the recorded run")
+        .option("--agent <agent-id>", "Reviewer agent identifier")
         .allowExcessArguments(false)
         .action(async (options) => {
-        const result = await runReviewCommand({ runId: options.run });
+        const result = await runReviewCommand({
+            runId: options.run,
+            agentId: options.agent,
+        });
         writeCommandOutput({
             body: result.body,
             stderr: result.stderr,

package/dist/commands/review/command.d.ts

@@ -2,9 +2,15 @@ import type { RunRecordEnhanced } from "../../runs/records/enhanced.js";
 export interface ReviewCommandInput {
     root: string;
     runsFilePath: string;
+    reviewsFilePath: string;
     runId: string;
+    agentId?: string;
 }
 export interface ReviewCommandResult {
+    reviewId: string;
     runRecord: RunRecordEnhanced;
+    agentId: string;
+    outputPath: string;
+    missingArtifacts: string[];
 }
 export declare function executeReviewCommand(input: ReviewCommandInput): Promise<ReviewCommandResult>;

package/dist/commands/review/command.js

@@ -1,9 +1,27 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { detectAgentProcessFailureDetail } from "../../agents/runtime/failures.js";
+import { runSandboxedAgent } from "../../agents/runtime/harness.js";
+import { AgentNotFoundError } from "../../configs/agents/errors.js";
+import { loadAgentById, loadAgentCatalog, } from "../../configs/agents/loader.js";
+import { loadEnvironmentConfig } from "../../configs/environment/loader.js";
+import { appendReviewRecord, finalizeReviewRecord, flushReviewRecordBuffer, } from "../../reviews/records/persistence.js";
 import { buildRunRecordView } from "../../runs/records/enhanced.js";
 import { RunRecordNotFoundError } from "../../runs/records/errors.js";
 import { fetchRunsSafely } from "../../runs/records/persistence.js";
+import { toErrorMessage } from "../../utils/errors.js";
+import { normalizePathForDisplay, relativeToRoot } from "../../utils/path.js";
+import { resolveRunWorkspacePaths, scaffoldAgentSessionWorkspace, } from "../../workspace/layout.js";
+import { promoteWorkspaceFile } from "../../workspace/promotion.js";
+import { REVIEW_ARTIFACT_INFO_FILENAME, REVIEW_FILENAME, VORATIQ_REVIEWS_DIR, } from "../../workspace/structure.js";
 import { RunNotFoundCliError } from "../errors.js";
+import { pruneWorkspace } from "../shared/prune.js";
+import { generateSessionId } from "../shared/session-id.js";
+import { ReviewAgentNotFoundError, ReviewGenerationFailedError, ReviewNoAgentsConfiguredError, } from "./errors.js";
+import { buildReviewManifest } from "./manifest.js";
+import { buildReviewPrompt } from "./prompt.js";
 export async function executeReviewCommand(input) {
-    const { root, runsFilePath, runId } = input;
+    const { root, runsFilePath, reviewsFilePath, runId, agentId } = input;
     const { records } = await fetchRunsSafely({
         root,
         runsFilePath,
@@ -22,5 +40,184 @@ export async function executeReviewCommand(input) {
     const enhanced = await buildRunRecordView(runRecord, {
         workspaceRoot: root,
     });
-    return { runRecord: enhanced };
+    const agent = resolveReviewAgent({ agentId, root });
+    const environment = loadEnvironmentConfig({ root });
+    const reviewId = generateSessionId();
+    const createdAt = new Date().toISOString();
+    const workspacePaths = await buildReviewWorkspace({
+        root,
+        reviewId,
+        agentId: agent.id,
+    });
+    const outputPath = normalizePathForDisplay(relativeToRoot(root, workspacePaths.reviewPath));
+    const record = {
+        sessionId: reviewId,
+        runId,
+        createdAt,
+        status: "running",
+        agentId: agent.id,
+        outputPath,
+    };
+    await appendReviewRecord({
+        root,
+        reviewsFilePath,
+        record,
+    });
+    const runWorkspaceAbsolute = resolveRunWorkspacePaths(root, runId).absolute;
+    let missingArtifacts = [];
+    try {
+        const buildManifestResult = await buildReviewManifest({
+            root,
+            run: enhanced,
+        });
+        const manifest = buildManifestResult.manifest;
+        missingArtifacts = buildManifestResult.missingArtifacts;
+        const artifactInfoWorkspacePath = join(workspacePaths.workspacePath, REVIEW_ARTIFACT_INFO_FILENAME);
+        await writeFile(artifactInfoWorkspacePath, `${JSON.stringify(manifest, null, 2)}\n`, {
+            encoding: "utf8",
+        });
+        const prompt = buildReviewPrompt({
+            runId: enhanced.runId,
+            runStatus: enhanced.status,
+            specPath: enhanced.spec.path,
+            baseRevisionSha: enhanced.baseRevisionSha,
+            createdAt: enhanced.createdAt,
+            completedAt: manifest.run.completedAt,
+            artifactInfoPath: REVIEW_ARTIFACT_INFO_FILENAME,
+            outputPath: REVIEW_FILENAME,
+            repoRootPath: root,
+            workspacePath: workspacePaths.workspacePath,
+        });
+        const result = await runSandboxedAgent({
+            root,
+            sessionId: reviewId,
+            agent,
+            prompt,
+            environment,
+            paths: {
+                agentRoot: workspacePaths.agentRoot,
+                workspacePath: workspacePaths.workspacePath,
+                sandboxHomePath: workspacePaths.sandboxHomePath,
+                runtimeManifestPath: workspacePaths.runtimeManifestPath,
+                sandboxSettingsPath: workspacePaths.sandboxSettingsPath,
+                runtimePath: workspacePaths.runtimePath,
+                artifactsPath: workspacePaths.artifactsPath,
+                stdoutPath: workspacePaths.stdoutPath,
+                stderrPath: workspacePaths.stderrPath,
+            },
+            captureChat: true,
+            extraWriteProtectedPaths: [runWorkspaceAbsolute],
+            extraReadProtectedPaths: [],
+        });
+        if (result.exitCode !== 0 || result.errorMessage) {
+            const detectedDetail = result.watchdog?.trigger && result.errorMessage
+                ? result.errorMessage
+                : await detectAgentProcessFailureDetail({
+                    provider: agent.provider,
+                    stdoutPath: workspacePaths.stdoutPath,
+                    stderrPath: workspacePaths.stderrPath,
+                });
+            const detail = detectedDetail ??
+                result.errorMessage ??
+                `Agent exited with code ${result.exitCode ?? "unknown"}`;
+            throw new ReviewGenerationFailedError([detail], [
+                `See stderr: ${normalizePathForDisplay(relativeToRoot(root, workspacePaths.stderrPath))}`,
+            ]);
+        }
+        await assertReviewOutputExists(root, workspacePaths, reviewId);
+        await promoteWorkspaceFile({
+            workspacePath: workspacePaths.workspacePath,
+            artifactsPath: workspacePaths.artifactsPath,
+            stagedRelativePath: REVIEW_FILENAME,
+            artifactRelativePath: REVIEW_FILENAME,
+            deleteStaged: true,
+        });
+        await finalizeReviewRecord({
+            root,
+            reviewsFilePath,
+            sessionId: reviewId,
+            status: "succeeded",
+        });
+    }
+    catch (error) {
+        const detail = error instanceof ReviewGenerationFailedError &&
+            error.detailLines.length > 0
+            ? error.detailLines.join("\n")
+            : toErrorMessage(error);
+        await finalizeReviewRecord({
+            root,
+            reviewsFilePath,
+            sessionId: reviewId,
+            status: "failed",
+            error: detail,
+        }).catch(() => { });
+        await flushReviewRecordBuffer({
+            reviewsFilePath,
+            sessionId: reviewId,
+        }).catch(() => { });
+        await pruneWorkspace(workspacePaths.workspacePath);
+        if (error instanceof ReviewGenerationFailedError) {
+            throw error;
+        }
+        throw new ReviewGenerationFailedError([detail], [
+            `See stderr: ${normalizePathForDisplay(relativeToRoot(root, workspacePaths.stderrPath))}`,
+        ]);
+    }
+    await flushReviewRecordBuffer({
+        reviewsFilePath,
+        sessionId: reviewId,
+    });
+    await pruneWorkspace(workspacePaths.workspacePath);
+    return {
+        reviewId,
+        runRecord: enhanced,
+        agentId: agent.id,
+        outputPath,
+        missingArtifacts,
+    };
+}
+function resolveReviewAgent(options) {
+    const { agentId, root } = options;
+    if (agentId) {
+        try {
+            return loadAgentById(agentId, { root });
+        }
+        catch (error) {
+            if (error instanceof AgentNotFoundError) {
+                throw new ReviewAgentNotFoundError(error.agentId);
+            }
+            throw error;
+        }
+    }
+    const catalog = loadAgentCatalog({ root });
+    const first = catalog[0];
+    if (!first) {
+        throw new ReviewNoAgentsConfiguredError();
+    }
+    return first;
+}
+async function buildReviewWorkspace(options) {
+    const { root, reviewId, agentId } = options;
+    return await scaffoldAgentSessionWorkspace({
+        root,
+        domain: VORATIQ_REVIEWS_DIR,
+        sessionId: reviewId,
+        agentId,
+    });
+}
+async function assertReviewOutputExists(root, workspacePaths, reviewId) {
+    const stagedPath = join(workspacePaths.workspacePath, REVIEW_FILENAME);
+    try {
+        const contents = await readFile(stagedPath, "utf8");
+        if (contents.trim().length > 0) {
+            return;
+        }
+    }
+    catch (error) {
+        const detail = toErrorMessage(error);
+        const stderrDisplay = normalizePathForDisplay(relativeToRoot(root, workspacePaths.stderrPath));
+        throw new ReviewGenerationFailedError([`Missing output: ${REVIEW_FILENAME}`], [`Review session: ${reviewId}`, detail, `See stderr: ${stderrDisplay}`]);
+    }
+    const stderrDisplay = normalizePathForDisplay(relativeToRoot(root, workspacePaths.stderrPath));
+    throw new ReviewGenerationFailedError([`Missing output: ${REVIEW_FILENAME}`], [`Review session: ${reviewId}`, `See stderr: ${stderrDisplay}`]);
 }

package/dist/commands/review/errors.d.ts

@@ -0,0 +1,14 @@
+import { CliError } from "../../cli/errors.js";
+export declare class ReviewError extends CliError {
+    constructor(headline: string, detailLines?: readonly string[], hintLines?: readonly string[]);
+}
+export declare class ReviewAgentNotFoundError extends ReviewError {
+    readonly agentId: string;
+    constructor(agentId: string);
+}
+export declare class ReviewNoAgentsConfiguredError extends ReviewError {
+    constructor();
+}
+export declare class ReviewGenerationFailedError extends ReviewError {
+    constructor(detailLines?: readonly string[], hintLines?: readonly string[]);
+}

package/dist/commands/review/errors.js

@@ -0,0 +1,27 @@
+import { CliError } from "../../cli/errors.js";
+export class ReviewError extends CliError {
+    constructor(headline, detailLines = [], hintLines = []) {
+        super(headline, detailLines, hintLines);
+        this.name = "ReviewError";
+    }
+}
+export class ReviewAgentNotFoundError extends ReviewError {
+    agentId;
+    constructor(agentId) {
+        super(`Agent "${agentId}" not found in agents.yaml.`, [], ["To add this agent, edit `.voratiq/agents.yaml`."]);
+        this.agentId = agentId;
+        this.name = "ReviewAgentNotFoundError";
+    }
+}
+export class ReviewNoAgentsConfiguredError extends ReviewError {
+    constructor() {
+        super("No enabled agents found in `.voratiq/agents.yaml`.");
+        this.name = "ReviewNoAgentsConfiguredError";
+    }
+}
+export class ReviewGenerationFailedError extends ReviewError {
+    constructor(detailLines = [], hintLines = []) {
+        super("Review generation failed.", detailLines, hintLines);
+        this.name = "ReviewGenerationFailedError";
+    }
+}

package/dist/commands/review/manifest.d.ts

@@ -0,0 +1,46 @@
+import type { RunRecordEnhanced } from "../../runs/records/enhanced.js";
+export type ReviewArtifactDescriptor = {
+    path: string;
+    exists: boolean;
+};
+export interface ReviewManifest {
+    version: number;
+    run: {
+        runId: string;
+        status: string;
+        specPath: string;
+        baseRevisionSha: string;
+        createdAt: string;
+        completedAt?: string;
+    };
+    agents: Array<{
+        agentId: string;
+        status: string;
+        commitSha?: string;
+        diffStatistics?: string;
+        artifacts: {
+            diff?: ReviewArtifactDescriptor;
+            chat?: ReviewArtifactDescriptor;
+            summary?: ReviewArtifactDescriptor;
+            stdout?: ReviewArtifactDescriptor;
+            stderr?: ReviewArtifactDescriptor;
+        };
+        evals: Array<{
+            slug: string;
+            status: string;
+            log?: ReviewArtifactDescriptor;
+            error?: string;
+            exitCode?: number | null;
+            command?: string;
+        }>;
+        error?: string;
+        warnings?: string[];
+    }>;
+}
+export declare function buildReviewManifest(options: {
+    root: string;
+    run: RunRecordEnhanced;
+}): Promise<{
+    manifest: ReviewManifest;
+    missingArtifacts: string[];
+}>;

package/dist/commands/review/manifest.js

@@ -0,0 +1,94 @@
+import { basename } from "node:path";
+import { pathExists } from "../../utils/fs.js";
+import { resolvePath } from "../../utils/path.js";
+export async function buildReviewManifest(options) {
+    const { root, run } = options;
+    const missingNames = [];
+    const seenMissing = new Set();
+    const noteMissing = (path) => {
+        const name = basename(path);
+        if (seenMissing.has(name)) {
+            return;
+        }
+        seenMissing.add(name);
+        missingNames.push(name);
+    };
+    const describe = async (repoRelativePath) => {
+        if (!repoRelativePath) {
+            return undefined;
+        }
+        const exists = await pathExists(resolvePath(root, repoRelativePath));
+        if (!exists) {
+            noteMissing(repoRelativePath);
+        }
+        return { path: repoRelativePath, exists };
+    };
+    const completedAt = resolveRunCompletedAt(run);
+    const agents = await Promise.all(run.agents.map(async (agent) => {
+        const artifacts = agent.assets;
+        const diff = await describe(artifacts.diffPath);
+        const chat = await describe(artifacts.chatPath);
+        const summary = await describe(artifacts.summaryPath);
+        const stdout = await describe(artifacts.stdoutPath);
+        const stderr = await describe(artifacts.stderrPath);
+        const evals = await Promise.all(agent.evals.map(async (evaluation) => ({
+            slug: evaluation.slug,
+            status: evaluation.status,
+            ...(typeof evaluation.exitCode === "number" ||
+                evaluation.exitCode === null
+                ? { exitCode: evaluation.exitCode }
+                : {}),
+            ...(evaluation.command ? { command: evaluation.command } : {}),
+            ...(evaluation.error ? { error: evaluation.error } : {}),
+            ...(evaluation.logPath
+                ? { log: await describe(evaluation.logPath) }
+                : {}),
+        })));
+        return {
+            agentId: agent.agentId,
+            status: agent.status,
+            ...(agent.commitSha ? { commitSha: agent.commitSha } : {}),
+            ...(agent.diffStatistics
+                ? { diffStatistics: agent.diffStatistics }
+                : {}),
+            artifacts: {
+                ...(diff ? { diff } : {}),
+                ...(chat ? { chat } : {}),
+                ...(summary ? { summary } : {}),
+                ...(stdout ? { stdout } : {}),
+                ...(stderr ? { stderr } : {}),
+            },
+            evals,
+            ...(agent.error ? { error: agent.error } : {}),
+            ...(agent.warnings ? { warnings: agent.warnings } : {}),
+        };
+    }));
+    return {
+        manifest: {
+            version: 1,
+            run: {
+                runId: run.runId,
+                status: run.status,
+                specPath: run.spec.path,
+                baseRevisionSha: run.baseRevisionSha,
+                createdAt: run.createdAt,
+                ...(completedAt ? { completedAt } : {}),
+            },
+            agents,
+        },
+        missingArtifacts: missingNames,
+    };
+}
+function resolveRunCompletedAt(run) {
+    let latest;
+    for (const agent of run.agents) {
+        const completedAt = agent.completedAt;
+        if (!completedAt) {
+            continue;
+        }
+        if (!latest || completedAt > latest) {
+            latest = completedAt;
+        }
+    }
+    return latest;
+}

package/dist/commands/review/prompt.d.ts

@@ -0,0 +1,13 @@
+export interface BuildReviewPromptOptions {
+    runId: string;
+    runStatus: string;
+    specPath: string;
+    baseRevisionSha: string;
+    createdAt: string;
+    completedAt?: string;
+    artifactInfoPath: string;
+    outputPath: string;
+    repoRootPath: string;
+    workspacePath: string;
+}
+export declare function buildReviewPrompt(options: BuildReviewPromptOptions): string;

package/dist/commands/review/prompt.js

@@ -0,0 +1,74 @@
+import { appendConstraints, appendOutputRequirements, } from "../shared/prompt-helpers.js";
+export function buildReviewPrompt(options) {
+    const { runId, runStatus, specPath, baseRevisionSha, createdAt, completedAt, artifactInfoPath, outputPath, repoRootPath, workspacePath, } = options;
+    const lines = [
+        "You are the reviewer for a completed Voratiq run.",
+        "Your job is to judge the quality of each agent's implementation, compare approaches, and recommend what to apply (if anything).",
+        "",
+        "Review goal:",
+        "- Help a human decide whether to apply any agent output.",
+        "- Lead with code quality and spec coverage; evals are secondary signals.",
+        "",
+        "Inputs:",
+        `- Run id: ${runId}`,
+        `- Status: ${runStatus}`,
+        `- Spec path: ${specPath}`,
+        `- Base revision: ${baseRevisionSha}`,
+        `- Created at: ${createdAt}`,
+        ...(completedAt ? [`- Completed at: ${completedAt}`] : []),
+        "",
+        `Run artifact information: \`${artifactInfoPath}\` (JSON, in the workspace root).`,
+        "- Use it as the index of what exists and where.",
+        "- If an artifact is missing or unreadable, call it out explicitly.",
+        "",
+        "Workflow (execute in order, no interaction):",
+        "1) Read the spec and capture key requirements/constraints.",
+        "2) Inspect each agent's artifacts listed in the artifact information (summary, diff, eval logs, stdout/stderr).",
+        "3) Evaluate implementation quality, spec coverage, and risks per agent.",
+        "4) Compare agents and rank them; weigh trade-offs.",
+        "5) Recommend whether to apply one, multiple, or none with explicit commands.",
+        "",
+        "Evaluation principles:",
+        "- Lead with code quality, clarity, and spec adherence.",
+        "- Treat evals as secondary diagnostic signals, not the primary decision driver.",
+        "- Prefer smaller, safer diffs when quality is otherwise comparable.",
+        "- Stay grounded in artifacts; cite file paths/behaviors.",
+        "- Call out follow-up work explicitly.",
+        "",
+        "Output template (use this structure):",
+        "",
+        `# Review of Run ${runId}`,
+        "",
+        "## Specification",
+        `**Path**: ${specPath}`,
+        "**Summary**: <1-2 sentence description of the spec>",
+        "",
+        "## Agent: <agent-id>",
+        "**Status**: <status>",
+        "**Quality**: High | Medium | Low",
+        "**Eval Signal**: <eval-slug> <status> | <eval-slug> <status> | … (use evals from the artifact information)",
+        "**Implementation Review**: <assess code quality, spec coverage, notable choices; cite eval insights as context>",
+        "**Follow-up Notes**: <issues, risks, or work needed post-apply>",
+        "<Repeat this section for each agent listed in the artifact information>",
+        "",
+        "## Comparison",
+        "<Synthesize differences and trade-offs across agents>",
+        "",
+        "## Risks / Missing Artifacts",
+        "<List missing or unreadable artifacts; explain impact>",
+        "",
+        "## Recommendation",
+        "**Preferred Agent(s)**: <agent-id(s) or `none`>",
+        "**Rationale**: <why these are best (or why none qualify)>",
+        "**Next Actions**:",
+        "<one line per recommendation, e.g. `voratiq apply --run <run-id> --agent <agent-id>`>",
+    ];
+    appendConstraints(lines, {
+        readAccess: repoRootPath,
+        writeAccess: workspacePath,
+    });
+    appendOutputRequirements(lines, [
+        `- Save the full review to \`${outputPath}\` in the workspace root.`,
+    ]);
+    return `${lines.join("\n")}\n`;
+}

package/dist/commands/run/shim/run-agent-shim.js

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
-import { readFile } from "node:fs/promises";
-import { dirname, isAbsolute, resolve as resolvePath } from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
 import { composeRestrictedEnvironment } from "../../../utils/env.js";
 import { GIT_AUTHOR_EMAIL, GIT_AUTHOR_NAME, GIT_COMMITTER_EMAIL, GIT_COMMITTER_NAME, } from "../../../utils/git.js";
@@ -169,6 +169,7 @@ async function launchAgent(options) {
     const workspacePath = isAbsolute(manifest.workspace)
         ? manifest.workspace
         : resolvePath(agentRoot, manifest.workspace);
+    await writeShellProfiles(manifest.env);
     const launchEnv = composeRestrictedEnvironment(manifest.env);
     // Agent commits generated outside the sandbox reuse this persona via
     // resolveSandboxPersona in src/commands/run/agents/lifecycle.ts.
@@ -214,6 +215,49 @@ async function launchAgent(options) {
         });
     });
 }
+async function writeShellProfiles(env) {
+    const homeDir = env.HOME;
+    if (!homeDir) {
+        return;
+    }
+    const bashrcPath = join(homeDir, ".bashrc");
+    const bashProfilePath = join(homeDir, ".bash_profile");
+    const exports = formatEnvExports(env);
+    const bashrcContents = `# Generated by Voratiq to preserve manifest env\n${exports}\n`;
+    const bashProfileContents = "# Generated by Voratiq to preserve manifest env\n" +
+        'if [ -f "$HOME/.bashrc" ]; then\n' +
+        '  . "$HOME/.bashrc"\n' +
+        "fi\n";
+    try {
+        await mkdir(homeDir, { recursive: true });
+        await writeFile(bashrcPath, bashrcContents, { encoding: "utf8" });
+        await writeFile(bashProfilePath, bashProfileContents, {
+            encoding: "utf8",
+        });
+    }
+    catch {
+        // Best-effort: shell profiles should not block agent startup.
+    }
+}
+function formatEnvExports(env) {
+    const lines = [];
+    const keys = Object.keys(env).sort((a, b) => a.localeCompare(b));
+    for (const key of keys) {
+        const value = env[key];
+        if (value === undefined) {
+            continue;
+        }
+        lines.push(`export ${key}=${shellEscape(value)}`);
+    }
+    return lines.join("\n");
+}
+function shellEscape(value) {
+    if (value.length === 0) {
+        return "''";
+    }
+    const singleQuoteEscape = "'\"'\"'";
+    return `'${value.replace(/'/g, singleQuoteEscape)}'`;
+}
 function logError(message) {
     console.error(`[voratiq] ${message}`);
 }

package/dist/commands/shared/preview.d.ts

@@ -0,0 +1,5 @@
+export interface MarkdownPreviewOptions {
+    language?: string;
+    pad?: boolean;
+}
+export declare function buildMarkdownPreviewLines(content: string, options?: MarkdownPreviewOptions): string[];