@hackerrank/astra-cli 0.1.22 → 0.1.24

package/README.md

@@ -80,7 +80,7 @@ astra -m claude-sonnet-5            # start chatting
 astra -m claude-sonnet-5 -y         # auto-run commands (no prompts)
 ```
 
-In-REPL commands: `/help /exit /clear /history /tokens /yolo`.
+In-REPL commands: `/help /plan <task> /exit /clear /history /tokens /yolo`.
 
 ### Autonomous task run
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hackerrank/astra-cli",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "Minimal zero-dependency AI coding agent for the HackerRank AI Gateway.",
   "type": "module",
   "bin": {

package/src/agent.js

@@ -200,7 +200,7 @@ export class Agent {
     if (output.returncode !== 0) this.nFailedCommands++;
 
     // --- 5. Submission sentinel ---
-    const submitted = checkSubmitted(output);
+    const submitted = command.trim() === `echo ${SUBMIT_SENTINEL}` ? checkSubmitted(output) : null;
     if (submitted != null) {
       return this.exit("Submitted", submitted);
     }

package/src/bench.js

@@ -18,6 +18,7 @@
  */
 
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { GatewayModel } from "./model.js";
@@ -146,7 +147,7 @@ export function seedWorkspace(workspace, { taskPath, taskFile, taskText } = {})
 
 /** Directory / file names never copied into a fresh workspace (kept clean so
  * result tarballs don't carry build cruft). */
-const COPY_SKIP = new Set([
+export const COPY_SKIP = new Set([
   "bench",
   ".git",
   "node_modules",
@@ -157,7 +158,7 @@ const COPY_SKIP = new Set([
 ]);
 
 /** Recursively copy a directory (skips build cruft — see COPY_SKIP). */
-function copyDir(from, to) {
+export function copyDir(from, to) {
   fs.mkdirSync(to, { recursive: true });
   for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
     if (COPY_SKIP.has(entry.name)) continue;
@@ -169,6 +170,16 @@ function copyDir(from, to) {
 }
 
 /** Build a metrics row object from a finished agent + run info. */
+/** Freeze an isolated workspace into a destination directory. */
+export function freezeWorkspace(from, to) {
+  fs.mkdirSync(to, { recursive: true });
+  for (const entry of fs.readdirSync(to, { withFileTypes: true })) {
+    if (COPY_SKIP.has(entry.name)) continue;
+    fs.rmSync(path.join(to, entry.name), { recursive: true, force: true });
+  }
+  copyDir(from, to);
+}
+
 export function collectMetrics({ agent, model, reasoning }) {
   const info = agent.serialize().info;
   const status = generationStatus(info.exit_status);
@@ -292,6 +303,7 @@ export async function runCell({
   reasoning,
   apiKey,
   baseUrl,
+  modelClient = null,
   task,
   taskPath,
   taskFile,
@@ -320,69 +332,79 @@ export async function runCell({
   fs.mkdirSync(alloc.workspace, { recursive: true });
   onStart({ ...alloc, model, reasoning });
 
+  const isolatedWorkspace = fs.mkdtempSync(path.join(os.tmpdir(), "astra-run-workspace-"));
   let taskText = task || "";
-  if (!resume) {
-    const seeded = seedWorkspace(alloc.workspace, { taskPath, taskFile, taskText: task });
-    taskText = seeded.taskText || task || "";
-    fs.writeFileSync(path.join(alloc.dir, "task.md"), taskText);
-  } else if (!taskText) {
-    taskText = fs.existsSync(path.join(alloc.dir, "task.md")) ? fs.readFileSync(path.join(alloc.dir, "task.md"), "utf8") : "";
-  }
-  writeProjectMetadata(alloc.dir, projectMetadata);
-
-  const gw = new GatewayModel({
-    model,
-    baseUrl,
-    apiKey,
-    modelKwargs: reasoningKwargs(reasoning),
-  });
-  const env = new LocalEnvironment({ cwd: alloc.workspace, timeout, maxOutputChars });
-  const sessionId = existingSessionId || newSessionId();
-  const agent = new Agent(gw, env, {
-    mode: "autonomous",
-    stepLimit: steps,
-    wallTimeLimitSeconds: wall,
-    outputPath: path.join(alloc.dir, "trajectory.json"),
-    sessionId,
-    saveSession,
-    task: taskText,
-    bench: { dir: alloc.dir, workspace: alloc.workspace, root: alloc.root, task: taskText, taskPath, model, reasoning, steps, wall, timeout, segments: [] },
-  });
-
-  if (resume && existingSessionId) {
-    const saved = loadSession(existingSessionId);
-    agent.restore(saved);
-    agent.exitStatus = null;
-    if (Number(steps) > 0) agent.stepLimit = agent.nSteps + Number(steps);
-    if (Number(wall) > 0) agent.wallTimeLimitSeconds = Math.ceil((Date.now() - agent.startTime) / 1000) + Number(wall);
-  }
-
-  let error = null;
   try {
+    if (!resume) {
+      const seeded = seedWorkspace(isolatedWorkspace, { taskPath, taskFile, taskText: task });
+      taskText = seeded.taskText || task || "";
+      fs.writeFileSync(path.join(alloc.dir, "task.md"), taskText);
+    } else {
+      if (fs.existsSync(alloc.workspace)) copyDir(alloc.workspace, isolatedWorkspace);
+      if (!taskText) {
+        taskText = fs.existsSync(path.join(alloc.dir, "task.md")) ? fs.readFileSync(path.join(alloc.dir, "task.md"), "utf8") : "";
+      }
+    }
+    writeProjectMetadata(alloc.dir, projectMetadata);
+
+    const gw = modelClient || new GatewayModel({
+      model,
+      baseUrl,
+      apiKey,
+      modelKwargs: reasoningKwargs(reasoning),
+    });
+    const env = new LocalEnvironment({ cwd: isolatedWorkspace, timeout, maxOutputChars });
+    const sessionId = existingSessionId || newSessionId();
+    const agent = new Agent(gw, env, {
+      mode: "autonomous",
+      stepLimit: steps,
+      wallTimeLimitSeconds: wall,
+      outputPath: path.join(alloc.dir, "trajectory.json"),
+      sessionId,
+      saveSession,
+      task: taskText,
+      bench: { dir: alloc.dir, workspace: alloc.workspace, root: alloc.root, task: taskText, taskPath, model, reasoning, steps, wall, timeout, segments: [] },
+    });
+
     if (resume && existingSessionId) {
-      while (true) {
-        if (agent.stepLimit > 0 && agent.nSteps >= agent.stepLimit) {
-          agent.exit("LimitsExceeded", "");
-          break;
+      const saved = loadSession(existingSessionId);
+      agent.restore(saved);
+      agent.exitStatus = null;
+      if (Number(steps) > 0) agent.stepLimit = agent.nSteps + Number(steps);
+      if (Number(wall) > 0) agent.wallTimeLimitSeconds = Math.ceil((Date.now() - agent.startTime) / 1000) + Number(wall);
+    }
+
+    let error = null;
+    try {
+      if (resume && existingSessionId) {
+        while (true) {
+          if (agent.stepLimit > 0 && agent.nSteps >= agent.stepLimit) {
+            agent.exit("LimitsExceeded", "");
+            break;
+          }
+          const turn = await agent.runTurn();
+          if (turn.kind === "exit") break;
         }
-        const turn = await agent.runTurn();
-        if (turn.kind === "exit") break;
+      } else {
+        await agent.run(taskText);
       }
-    } else {
-      await agent.run(taskText);
+    } catch (err) {
+      error = String(err?.message || err);
+      if (!agent.exitStatus) agent.exit("Error", "");
     }
-  } catch (err) {
-    error = String(err?.message || err);
-    if (!agent.exitStatus) agent.exit("Error", "");
-  }
 
-  const metrics = collectMetrics({ agent, model: gw, reasoning });
-  if (error) metrics.exit_status = metrics.exit_status || "Error";
-  const paths = writeMetrics({ runDir: alloc.dir, root: alloc.root, metrics });
+    freezeWorkspace(isolatedWorkspace, alloc.workspace);
 
-  const result = { ...metrics, error, slug: alloc.slug, runId: alloc.runId, dir: alloc.dir, sessionId, cell, paths };
-  onDone(result);
-  return result;
+    const metrics = collectMetrics({ agent, model: gw, reasoning });
+    if (error) metrics.exit_status = metrics.exit_status || "Error";
+    const paths = writeMetrics({ runDir: alloc.dir, root: alloc.root, metrics });
+
+    const result = { ...metrics, error, slug: alloc.slug, runId: alloc.runId, dir: alloc.dir, sessionId, cell, paths };
+    onDone(result);
+    return result;
+  } finally {
+    try { fs.rmSync(isolatedWorkspace, { recursive: true, force: true }); } catch {}
+  }
 }
 
 /**

package/src/cli.js

@@ -74,6 +74,7 @@
  */
 
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { GatewayModel } from "./model.js";
 import { LocalEnvironment } from "./environment.js";
@@ -92,6 +93,8 @@ import { runRepl } from "./repl.js";
 import { ProjectConfigError, loadProject } from "./project.js";
 import {
   allocateRun,
+  copyDir,
+  freezeWorkspace,
   seedWorkspace,
   collectMetrics,
   writeMetrics,
@@ -202,7 +205,10 @@ async function main() {
   let task = args.task;
   if (args["task-file"]) task = fs.readFileSync(args["task-file"], "utf8");
   let resumeBench = resumeDoc?.bench ?? null;
-  if (args.bench && args.resume && !resumeBench) {
+  // Project benches resume from their task ledger, not from an interactive
+  // session document. Applying this guard to both paths stranded a leased
+  // project cell before its first model reply.
+  if (args.bench && args.resume && !args.project && !resumeBench) {
     console.error("\x1b[31m[astra] request_error: this session is not a bench run.\x1b[0m");
     process.exit(2);
   }
@@ -391,6 +397,7 @@ async function main() {
   // workspace under bench/<model-name-reasoning>/run-NN/. The agent's commands
   // run inside that workspace and metrics are recorded when it finishes.
   let benchRun = null;
+  let isolatedWorkspace = null;
   if (mode === "autonomous" && resumeBench) {
     if (!fs.existsSync(resumeBench.dir) || !fs.existsSync(resumeBench.workspace)) {
       console.error("\x1b[31m[astra] request_error: saved bench workspace is missing.\x1b[0m");
@@ -403,11 +410,14 @@ async function main() {
       slug: path.basename(path.dirname(resumeBench.dir)),
       runId: path.basename(resumeBench.dir),
     };
+    isolatedWorkspace = fs.mkdtempSync(path.join(os.tmpdir(), "astra-run-workspace-"));
+    if (fs.existsSync(benchRun.workspace)) copyDir(benchRun.workspace, isolatedWorkspace);
     resumeBench.segments = Array.isArray(resumeBench.segments) ? resumeBench.segments : [];
     resumeBench.segments.push({ started_at: new Date().toISOString(), resumed: true });
   } else if (mode === "autonomous" && !resumeDoc) {
     benchRun = allocateRun({ model: modelId, reasoning, root: args["bench-root"] });
-    const seeded = seedWorkspace(benchRun.workspace, {
+    isolatedWorkspace = fs.mkdtempSync(path.join(os.tmpdir(), "astra-run-workspace-"));
+    const seeded = seedWorkspace(isolatedWorkspace, {
       taskPath: args.path,
       taskFile: args["task-file"],
       taskText: task,
@@ -431,7 +441,7 @@ async function main() {
     };
   }
 
-  const cmdCwd = benchRun?.workspace || cwd;
+  const cmdCwd = isolatedWorkspace || benchRun?.workspace || cwd;
   const env = new LocalEnvironment({
     cwd: cmdCwd,
     timeout: Number(args.timeout),
@@ -478,29 +488,35 @@ async function main() {
     // an isolated workspace under bench/<model-name-reasoning>/run-NN/.
     const runBench = async (taskText, log) => {
       const alloc = allocateRun({ model: modelId, reasoning, root: args["bench-root"] });
-      seedWorkspace(alloc.workspace, { taskText });
-      fs.writeFileSync(path.join(alloc.dir, "task.md"), taskText || "");
-      log(`[astra] bench ${alloc.slug}/${alloc.runId} → ${alloc.workspace}`);
-      const benchEnv = new LocalEnvironment({
-        cwd: alloc.workspace,
-        timeout: Number(args.timeout),
-        maxOutputChars: Number(args["max-output"]),
-      });
-      const benchAgent = new Agent(model, benchEnv, {
-        mode: "autonomous",
-        stepLimit: Number(args.steps),
-        wallTimeLimitSeconds: Number(args.wall),
-        outputPath: path.join(alloc.dir, "trajectory.json"),
-      });
-      const res = await benchAgent.run(taskText);
-      const metrics = collectMetrics({ agent: benchAgent, model, reasoning });
-      const paths = writeMetrics({ runDir: alloc.dir, root: alloc.root, metrics });
-      log(`[astra] bench done: exit=${res.exit_status} · metrics → ${paths.runMetrics}`);
+      const benchIsolated = fs.mkdtempSync(path.join(os.tmpdir(), "astra-run-workspace-"));
       try {
-        const report = refreshReport(alloc.root);
-        log(`[astra] report → ${report.html}`);
-      } catch (err) {
-        log(`[astra] report generation skipped: ${err.message}`);
+        seedWorkspace(benchIsolated, { taskText });
+        fs.writeFileSync(path.join(alloc.dir, "task.md"), taskText || "");
+        log(`[astra] bench ${alloc.slug}/${alloc.runId} → ${alloc.workspace}`);
+        const benchEnv = new LocalEnvironment({
+          cwd: benchIsolated,
+          timeout: Number(args.timeout),
+          maxOutputChars: Number(args["max-output"]),
+        });
+        const benchAgent = new Agent(model, benchEnv, {
+          mode: "autonomous",
+          stepLimit: Number(args.steps),
+          wallTimeLimitSeconds: Number(args.wall),
+          outputPath: path.join(alloc.dir, "trajectory.json"),
+        });
+        const res = await benchAgent.run(taskText);
+        freezeWorkspace(benchIsolated, alloc.workspace);
+        const metrics = collectMetrics({ agent: benchAgent, model, reasoning });
+        const paths = writeMetrics({ runDir: alloc.dir, root: alloc.root, metrics });
+        log(`[astra] bench done: exit=${res.exit_status} · metrics → ${paths.runMetrics}`);
+        try {
+          const report = refreshReport(alloc.root);
+          log(`[astra] report → ${report.html}`);
+        } catch (err) {
+          log(`[astra] report generation skipped: ${err.message}`);
+        }
+      } finally {
+        try { fs.rmSync(benchIsolated, { recursive: true, force: true }); } catch {}
       }
     };
     await runRepl(agent, { model, autoRun: !!args.yolo, fresh: !resumeDoc, reasoning, runBench });
@@ -544,6 +560,7 @@ async function main() {
     }
     agent.save();
     if (benchRun) {
+      if (isolatedWorkspace) freezeWorkspace(isolatedWorkspace, benchRun.workspace);
       writeMetrics({
         runDir: benchRun.dir,
         root: benchRun.root,
@@ -552,6 +569,11 @@ async function main() {
       try { refreshReport(benchRun.root); } catch {}
     }
     throw error;
+  } finally {
+    if (benchRun && isolatedWorkspace) {
+      freezeWorkspace(isolatedWorkspace, benchRun.workspace);
+      try { fs.rmSync(isolatedWorkspace, { recursive: true, force: true }); } catch {}
+    }
   }
   agent.save();
 

package/src/environment.js

@@ -17,11 +17,12 @@ export class LocalEnvironment {
    * @param {object} [opts.env]      extra env vars merged over process.env
    * @param {number} [opts.maxOutputChars] cap on observation size (default 16000)
    */
-  constructor({ cwd = process.cwd(), timeout = 60, env = {}, maxOutputChars = 16000 } = {}) {
+  constructor({ cwd = process.cwd(), timeout = 60, env = {}, maxOutputChars = 16000, inheritEnv = true } = {}) {
     this.cwd = cwd;
     this.timeout = timeout;
     this.env = env;
     this.maxOutputChars = maxOutputChars;
+    this.inheritEnv = inheritEnv;
   }
 
   /**
@@ -33,7 +34,10 @@ export class LocalEnvironment {
     return new Promise((resolve) => {
       const child = spawn("bash", ["-c", command], {
         cwd: this.cwd,
-        env: { ...process.env, ...this.env },
+        // Evaluators must never leak their gateway credential into a command
+        // that reads an untrusted candidate workspace.  Normal agent sessions
+        // retain the historical inherited environment.
+        env: this.inheritEnv ? { ...process.env, ...this.env } : { ...this.env },
         // New process group so we can kill the whole tree on timeout.
         detached: process.platform !== "win32",
       });

package/src/evaluator-cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import { runEvaluator } from "./evaluator.js";
+
+function options(argv) {
+  const result = {};
+  for (let index = 2; index < argv.length; index += 2) {
+    const key = argv[index];
+    if (!key?.startsWith("--") || argv[index + 1] == null) throw new Error(`invalid evaluator option: ${key || ""}`);
+    result[key.slice(2)] = argv[index + 1];
+  }
+  for (const key of ["prompt-file", "workspace", "output", "model"]) if (!result[key]) throw new Error(`--${key} is required`);
+  return result;
+}
+
+try {
+  const args = options(process.argv);
+  const prompt = fs.readFileSync(args["prompt-file"], "utf8");
+  const result = await runEvaluator({ prompt, workspace: args.workspace, outputPath: args.output, model: args.model,
+    reasoning: args.reasoning || "high", apiKey: process.env.ASTRA_GATEWAY_API_KEY,
+    baseUrl: process.env.ASTRA_GATEWAY_BASE_URL, timeout: args.timeout || 0, steps: args.steps || 0, wall: args.wall || 0 });
+  process.stdout.write(JSON.stringify(result.metrics) + "\n");
+} catch (error) {
+  process.stderr.write(`ASTRA evaluator error: ${error.message}\n`);
+  process.exitCode = 2;
+}

package/src/evaluator.js

@@ -0,0 +1,49 @@
+/** ASTRA-owned agentic evaluator for task verifiers. */
+import fs from "node:fs";
+import path from "node:path";
+import { GatewayModel } from "./model.js";
+import { LocalEnvironment } from "./environment.js";
+import { Agent } from "./agent.js";
+
+const SAFE_COMMAND_ENV = new Set([
+  "PATH", "HOME", "TMPDIR", "LANG", "LANGUAGE", "LC_ALL", "TZ",
+  "ADMIN_USERNAME", "ADMIN_PASSWORD", "DATABASE_URL", "MONGODB_URI", "REDIS_URL",
+  "PLAYWRIGHT_BROWSERS_PATH", "PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD",
+]);
+
+export function evaluatorCommandEnvironment(source = process.env) {
+  return Object.fromEntries(Object.entries(source).filter(([key]) =>
+    SAFE_COMMAND_ENV.has(key) || key.startsWith("LC_"),
+  ));
+}
+
+export function evaluatorTask({ prompt, outputPath }) {
+  return `You are ASTRA's trusted verifier evaluator. Inspect the application and its source to answer the evaluation request below. Treat the candidate workspace as read-only: do not edit, delete, install into, or format files there. You may read files and make the explicitly requested HTTP/database probes.\n\nReturn exactly one JSON object that satisfies the requested response shape. Write only that JSON object to ${outputPath} (outside the candidate workspace), then run: printf 'COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT'. Keep commands small.\n\nEvaluation request:\n${prompt}`;
+}
+
+export async function runEvaluator({ prompt, workspace, outputPath, model, reasoning, apiKey, baseUrl, timeout = 0, steps = 0, wall = 0 }) {
+  const destination = path.resolve(outputPath);
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  try { fs.rmSync(destination, { force: true }); } catch {}
+  const gateway = new GatewayModel({
+    model,
+    apiKey,
+    baseUrl,
+    modelKwargs: reasoning ? { reasoning_effort: reasoning } : {},
+  });
+  const env = new LocalEnvironment({
+    cwd: path.resolve(workspace), timeout: Number(timeout), maxOutputChars: 12000,
+    env: evaluatorCommandEnvironment(), inheritEnv: false,
+  });
+  const agent = new Agent(gateway, env, {
+    mode: "autonomous", stepLimit: Number(steps), wallTimeLimitSeconds: Number(wall),
+  });
+  const result = await agent.run(evaluatorTask({ prompt, outputPath: destination }));
+  if (result.exit_status !== "Submitted") {
+    throw new Error(`ASTRA evaluator did not submit: ${result.exit_status}`);
+  }
+  if (!fs.existsSync(destination)) throw new Error("ASTRA evaluator did not produce its JSON answer");
+  const answer = fs.readFileSync(destination, "utf8");
+  JSON.parse(answer);
+  return { answer, metrics: { calls: gateway.nCalls, retries: gateway.nRetries, costUsd: gateway.totalCostUsd } };
+}

package/src/model.js

@@ -42,7 +42,7 @@ export class GatewayModel {
    * @param {number} [opts.maxRetries]
    * @param {(info:object)=>void} [opts.onRetry] called before each retry sleep
    */
-  constructor({ model, baseUrl, apiKey, modelKwargs = {}, maxRetries = 5, maxTokens = 8192, requestTimeoutMs = 300000, onRetry } = {}) {
+  constructor({ model, baseUrl, apiKey, modelKwargs = {}, maxRetries = 5, maxTokens = 8192, requestTimeoutMs = 0, onRetry } = {}) {
     if (!model) throw new Error("GatewayModel: `model` is required");
     this.model = model;
     this.maxTokens = maxTokens;
@@ -98,8 +98,8 @@ export class GatewayModel {
     let lastErr;
     for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
       try {
-        const timeoutSignal = AbortSignal.timeout(this.requestTimeoutMs);
-        const signal = this.signal ? AbortSignal.any([this.signal, timeoutSignal]) : timeoutSignal;
+        const timeoutSignal = this.requestTimeoutMs > 0 ? AbortSignal.timeout(this.requestTimeoutMs) : null;
+        const signal = timeoutSignal && this.signal ? AbortSignal.any([this.signal, timeoutSignal]) : (timeoutSignal || this.signal || undefined);
         const res = await fetch(`${this.baseUrl}/chat/completions`, {
           method: "POST",
           headers: {

package/src/project-bench.js

@@ -97,6 +97,7 @@ export async function runProjectBench({ project, apiKey, baseUrl, quiet = false,
           runDir,
           candidateDir,
           config: project.verification,
+          gateway: { apiKey, baseUrl },
           expected: { taskId: project.id, taskVersion: project.version, candidateSha256 },
         });
       } catch (error) {

package/src/project.js

@@ -75,7 +75,11 @@ function verificationConfig(value) {
     baseUrl: verification.base_url === undefined ? null : requireString(verification.base_url, "verification.base_url"),
     readinessUrl: verification.readiness_url === undefined ? null : requireString(verification.readiness_url, "verification.readiness_url"),
     tokenEnv: verification.token_env === undefined ? null : requireString(verification.token_env, "verification.token_env"),
-    timeoutSeconds: positiveInteger(verification.timeout_seconds, "verification.timeout_seconds", 3600),
+    evaluatorModel: verification.evaluator_model === undefined ? null : requireString(verification.evaluator_model, "verification.evaluator_model"),
+    evaluatorReasoning: verification.evaluator_reasoning === undefined ? null : requireString(verification.evaluator_reasoning, "verification.evaluator_reasoning"),
+    // Zero means no verifier deadline. Tasks with agentic verification choose
+    // completion over an arbitrary wall-clock cutoff.
+    timeoutSeconds: positiveInteger(verification.timeout_seconds, "verification.timeout_seconds", 0, { allowZero: true }),
     report: verification.report === undefined ? "verifier-report.json" : requireString(verification.report, "verification.report"),
   };
 }

package/src/prompts.js

@@ -102,3 +102,27 @@ export function render(template, vars) {
     key in vars && vars[key] != null ? String(vars[key]) : ""
   );
 }
+
+export const PLAN_PROMPT_TEMPLATE = `Please explore the workspace and create a clear, actionable plan for this task:
+
+Task:
+{{task}}
+
+Instructions for planning:
+1. Run read-only commands (e.g. ls, find, grep, cat) to explore and understand the relevant files.
+2. Present a structured plan with:
+   - **Objective & Scope**: Summary of what needs to be done.
+   - **Files to Modify / Create**: List of target files.
+   - **Self-Testing & Verification Strategy**: Exact test commands or verification scripts to write/run.
+   - **Self-Review Checklist**: Code quality, edge cases, and cleanliness checks.
+3. Finish with a chat response presenting the complete plan so the user can review it before execution.`;
+
+export const AUTONOMOUS_EXECUTION_PROMPT = `The plan has been approved. Execute the plan end-to-end now in autonomous mode without asking further questions.
+
+Workflow requirements:
+1. Implement the changes with clean, focused edits.
+2. Self-verify by writing or running test scripts to prove the solution works.
+3. Review your changes with \`git diff\` (or inspect modified files) to ensure no regressions, unintended files, or debug prints remain.
+4. If any tests or checks fail, diagnose and fix the errors.
+5. When completely finished, verified, and reviewed, run:
+\`echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT\``;

package/src/repl.js

@@ -17,6 +17,7 @@ import readline from "node:readline";
 import { fileURLToPath } from "node:url";
 import { ask, saveAgentPrefs } from "./config.js";
 import { AVAILABLE_MODELS, REASONING_LEVELS } from "./models.js";
+import { PLAN_PROMPT_TEMPLATE, AUTONOMOUS_EXECUTION_PROMPT, render } from "./prompts.js";
 
 const C = {
   dim: (s) => `\x1b[2m${s}\x1b[0m`,
@@ -517,6 +518,7 @@ Interactive commands:
   /help            show this help
   /exit, /quit     leave (session is saved)
   /clear           start a fresh conversation (new context)
+  /plan <task>     plan a task, review it, then execute autonomously with self-review
   /history         print the message history
   /tokens          show token usage so far
   /yolo            toggle auto-run of commands (no confirmation)
@@ -643,6 +645,25 @@ async function runStickyRepl(agent, model, yolo, intro = [], { runBench = null }
         if (cmd === "history") { printHistory(agent, log); continue; }
         if (cmd === "tokens") { log(tokensLine(model)); continue; }
         if (cmd === "yolo") { yolo = !yolo; log(C.dim(`[astra] auto-run ${yolo ? "ON" : "OFF"}.`)); refresh(); continue; }
+        if (cmd === "plan") {
+          const taskText = line.slice(line.indexOf("plan") + 4).trim();
+          const prevYolo = yolo;
+          await handlePlanWorkflow({
+            taskText,
+            agent,
+            model,
+            log,
+            readInput: (promptText) => screen.readLine(promptText, { guardEnter: true, echo: true }),
+            startBusy: (label) => screen.startBusy(label),
+            stopBusy: () => screen.stopBusy(),
+            interrupt,
+            setYolo: (v) => { yolo = v; },
+            onProgress: () => refresh(),
+          });
+          yolo = prevYolo;
+          refresh();
+          continue;
+        }
         log(C.dim(`[astra] unknown command: /${cmd} (try /help)`));
         continue;
       }
@@ -742,6 +763,25 @@ async function runPlainRepl(agent, model, yolo) {
         if (cmd === "history") { printHistory(agent, log); continue; }
         if (cmd === "tokens") { console.error(tokensLine(model)); continue; }
         if (cmd === "yolo") { yolo = !yolo; console.error(C.dim(`[astra] auto-run ${yolo ? "ON" : "OFF"}.`)); continue; }
+        if (cmd === "plan") {
+          const taskText = line.slice(line.indexOf("plan") + 4).trim();
+          const prevYolo = yolo;
+          await handlePlanWorkflow({
+            taskText,
+            agent,
+            model,
+            log: (t) => console.error(t),
+            readInput: (promptText) => new Promise((res) => rl.question(promptText, res)),
+            startBusy: () => {},
+            stopBusy: () => {},
+            interrupt: { aborted: false, quit: false },
+            setYolo: (v) => { yolo = v; },
+            onProgress: () => printFooterInline(agent, model, yolo),
+          });
+          yolo = prevYolo;
+          printFooterInline(agent, model, yolo);
+          continue;
+        }
         console.error(C.dim(`[astra] unknown command: /${cmd} (try /help)`));
         continue;
       }
@@ -859,3 +899,161 @@ function tokensLine(model) {
   const dollars = usd < 0.01 ? "$" + usd.toFixed(5) : "$" + usd.toFixed(4);
   return C.dim(`[astra] tokens: prompt=${pt} completion=${ct} total=${pt + ct} · cost=${dollars} (${src})`);
 }
+
+
+/**
+ * Run the plan-and-execute workflow:
+ * 1. Prompt model to explore workspace and draft a structured plan.
+ * 2. Pause and prompt user for approval / feedback.
+ * 3. On approval, execute autonomously to completion with auto-review and auto-fix.
+ */
+export async function handlePlanWorkflow({
+  taskText,
+  agent,
+  model,
+  log,
+  readInput,
+  startBusy,
+  stopBusy,
+  interrupt,
+  setYolo = () => {},
+  onProgress = () => {},
+}) {
+  let task = taskText;
+  if (!task) {
+    task = (await readInput(C.yellow("Enter task to plan: "))).trim();
+  }
+  if (!task) {
+    log(C.dim("[astra] plan cancelled (empty task)."));
+    return;
+  }
+
+  log(C.cyan(`[astra] exploring workspace and drafting plan for: "${task}"...`));
+  agent.addUserMessage(render(PLAN_PROMPT_TEMPLATE, { task }));
+
+  model._abort = new AbortController();
+  model.signal = model._abort.signal;
+  startBusy("planning");
+  try {
+    await driveUntilChat(agent, log, interrupt);
+  } finally {
+    stopBusy();
+    model.signal = null;
+    model._abort = null;
+  }
+  if (interrupt?.quit || interrupt?.aborted) return;
+
+  // Review gate loop
+  let approved = false;
+  while (!approved) {
+    const ans = (await readInput(
+      C.yellow("\nApprove plan and begin autonomous execution? [Y/n/feedback] ")
+    )).trim();
+    const lower = ans.toLowerCase();
+
+    if (lower === "n" || lower === "no" || lower === "cancel" || lower === "abort") {
+      log(C.dim("[astra] plan cancelled. Returning to interactive mode."));
+      return;
+    }
+    if (ans === "" || lower === "y" || lower === "yes") {
+      approved = true;
+      break;
+    }
+
+    // Feedback provided: refine plan
+    log(C.cyan(`[astra] updating plan with feedback: "${ans}"...`));
+    agent.addUserMessage(
+      `Here is feedback on the plan: "${ans}". Please refine the plan accordingly and present the updated plan.`
+    );
+    model._abort = new AbortController();
+    model.signal = model._abort.signal;
+    startBusy("planning");
+    try {
+      await driveUntilChat(agent, log, interrupt);
+    } finally {
+      stopBusy();
+      model.signal = null;
+      model._abort = null;
+    }
+    if (interrupt?.quit || interrupt?.aborted) return;
+  }
+
+  // Execute autonomously
+  log(C.green("\n[astra] plan approved! Starting unattended autonomous execution with auto-review & auto-fix..."));
+  const prevMode = agent.mode;
+  setYolo(true);
+  agent.mode = "autonomous";
+  agent.addUserMessage(AUTONOMOUS_EXECUTION_PROMPT);
+
+  model._abort = new AbortController();
+  model.signal = model._abort.signal;
+  startBusy("executing plan");
+  let status = "Completed";
+  try {
+    status = await driveAutonomous(agent, log, interrupt);
+  } catch (err) {
+    log(C.red(`[astra] error during autonomous execution: ${err?.message || err}`));
+    status = "Error";
+  } finally {
+    stopBusy();
+    model.signal = null;
+    model._abort = null;
+    agent.mode = prevMode;
+    agent.exitStatus = null;
+    onProgress();
+  }
+
+  log(C.green(`\n[astra] plan execution finished (${status}). You are now back in interactive mode.`));
+}
+
+/**
+ * Drive turns autonomously until the model submits with the completion sentinel.
+ */
+export async function driveAutonomous(agent, log, interrupt = null) {
+  while (true) {
+    if (interrupt && interrupt.aborted) {
+      log(C.yellow("[astra] autonomous execution interrupted — returning to prompt."));
+      return "Interrupted";
+    }
+    let turn;
+    try {
+      turn = await agent.runTurn();
+    } catch (err) {
+      if (err && (err.name === "GatewayError" || err.name === "ContextWindowError")) {
+        log(C.red(`[astra] ${err.message}`));
+        return err.name;
+      }
+      throw err;
+    }
+
+    if (interrupt && interrupt.aborted) {
+      log(C.yellow("[astra] autonomous execution interrupted — returning to prompt."));
+      return "Interrupted";
+    }
+    if (turn.kind === "exit") {
+      log(C.dim(`[astra] autonomous run ended: ${turn.exit_status}`));
+      return turn.exit_status;
+    }
+    if (turn.kind === "command") {
+      const rc = turn.returncode;
+      const tag = rc === 0 ? C.dim(`[rc ${rc}]`) : C.red(`[rc ${rc}]`);
+      log(tag + "\n" + indent(turn.output));
+      continue;
+    }
+    if (turn.kind === "declined") {
+      log(C.dim("[astra] command skipped."));
+      continue;
+    }
+    if (turn.kind === "format_error") {
+      log(C.dim(`[astra] (reprompting: ${turn.error})`));
+      continue;
+    }
+    if (turn.kind === "chat") {
+      log("\n" + C.cyan("astra › ") + turn.content.trim());
+      agent.addUserMessage(
+        "Continue executing the approved plan in autonomous mode. When all changes are implemented, tested, and self-reviewed, run:\necho COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT"
+      );
+      continue;
+    }
+  }
+}

package/src/verifier-runner.js

@@ -13,36 +13,52 @@ function redactOutput(value) {
 
 function runCommand(command, { cwd, env, timeoutSeconds }) {
   return new Promise((resolve) => {
-    const child = spawn(command, { cwd, env, shell: true, stdio: ["ignore", "pipe", "pipe"] });
+    const child = spawn(command, { cwd, env, shell: true, detached: process.platform !== "win32", stdio: ["ignore", "pipe", "pipe"] });
     let stdout = "";
     let stderr = "";
     child.stdout.on("data", (chunk) => { stdout += chunk; });
     child.stderr.on("data", (chunk) => { stderr += chunk; });
     let timedOut = false;
-    const timer = setTimeout(() => {
+    const limit = Number(timeoutSeconds);
+    const timer = limit > 0 ? setTimeout(() => {
       timedOut = true;
-      child.kill("SIGTERM");
-      setTimeout(() => child.kill("SIGKILL"), 250);
-    }, Math.max(1, Number(timeoutSeconds) || 3600) * 1000);
+      stopProcessTree(child, "SIGTERM");
+      setTimeout(() => stopProcessTree(child, "SIGKILL"), 250);
+    }, limit * 1000) : null;
     child.on("close", (code, signal) => {
-      clearTimeout(timer);
+      if (timer) clearTimeout(timer);
       resolve({ code, signal, timedOut, stdout, stderr });
     });
     child.on("error", (error) => {
-      clearTimeout(timer);
+      if (timer) clearTimeout(timer);
       resolve({ code: null, signal: null, timedOut: false, stdout, stderr: `${stderr}${error.message}` });
     });
   });
 }
 
+function stopProcessTree(child, signal) {
+  try {
+    if (process.platform !== "win32" && child.pid) process.kill(-child.pid, signal);
+    else child.kill(signal);
+  } catch {
+    // The command may already have exited between the timer and the signal.
+  }
+}
+
 function startProcess(command, { cwd, env }) {
-  return spawn(command, { cwd, env, shell: true, stdio: ["ignore", "ignore", "ignore"] });
+  const child = spawn(command, { cwd, env, shell: true, detached: process.platform !== "win32", stdio: ["ignore", "pipe", "pipe"] });
+  let output = "";
+  child.stdout.on("data", (chunk) => { output += chunk; });
+  child.stderr.on("data", (chunk) => { output += chunk; });
+  child.startupOutput = () => redactOutput(output);
+  return child;
 }
 
 async function acquireVerifierLock(projectRoot, timeoutSeconds) {
   const lockPath = path.join(projectRoot, ".astra", "verifier.lock");
   fs.mkdirSync(path.dirname(lockPath), { recursive: true });
-  const deadline = Date.now() + Math.max(1, Number(timeoutSeconds) || 3600) * 1000;
+  const limit = Number(timeoutSeconds);
+  const deadline = limit > 0 ? Date.now() + limit * 1000 : Infinity;
   while (Date.now() < deadline) {
     try {
       const descriptor = fs.openSync(lockPath, "wx");
@@ -71,21 +87,25 @@ async function acquireVerifierLock(projectRoot, timeoutSeconds) {
   throw new Error("timed out waiting for the task verifier lock");
 }
 
-async function waitReady(url, timeoutSeconds) {
-  const deadline = Date.now() + Math.max(1, Number(timeoutSeconds) || 30) * 1000;
+async function waitReady(url, timeoutSeconds, candidateProcess) {
+  const limit = Number(timeoutSeconds);
+  const deadline = limit > 0 ? Date.now() + limit * 1000 : Infinity;
   while (Date.now() < deadline) {
+    if (candidateProcess && candidateProcess.exitCode !== null) {
+      return { ready: false, exited: true, output: candidateProcess.startupOutput?.() || "" };
+    }
     try {
       const response = await fetch(url, { signal: AbortSignal.timeout(1000) });
-      if (response.ok) return true;
+      if (response.ok) return { ready: true, exited: false, output: "" };
     } catch {
       // Candidate is still starting.
     }
     await new Promise((resolve) => setTimeout(resolve, 250));
   }
-  return false;
+  return { ready: false, exited: false, output: candidateProcess?.startupOutput?.() || "" };
 }
 
-export async function runVerifier({ project, cell, runDir, candidateDir, config, expected = {} }) {
+export async function runVerifier({ project, cell, runDir, candidateDir, config, expected = {}, gateway = {} }) {
   const started = Date.now();
   fs.mkdirSync(runDir, { recursive: true });
   const reportPath = path.resolve(runDir, config.report || "verifier.json");
@@ -107,6 +127,14 @@ export async function runVerifier({ project, cell, runDir, candidateDir, config,
     ASTRA_TASK_TYPE: project.type || "brownfield",
     ASTRA_CELL_KEY: cell.cellKey,
     ASTRA_PROJECT_ROOT: project.root,
+    // The task verifier invokes ASTRA's evaluator bridge for dynamic discovery
+    // and source judgment. Keep this explicit and task-scoped: the candidate
+    // command environment is separately scrubbed by the verifier.
+    ASTRA_EVALUATOR_BIN: new URL("./evaluator-cli.js", import.meta.url).pathname,
+    ...(gateway.apiKey ? { ASTRA_GATEWAY_API_KEY: gateway.apiKey } : {}),
+    ...(gateway.baseUrl ? { ASTRA_GATEWAY_BASE_URL: gateway.baseUrl } : {}),
+    ASTRA_EVALUATOR_MODEL: config.evaluatorModel || cell.model,
+    ASTRA_EVALUATOR_REASONING: config.evaluatorReasoning || cell.reasoning || "high",
     ...(config.baseUrl ? { SCIM_BASE_URL: config.baseUrl } : {}),
     ...(config.tokenEnv && process.env[config.tokenEnv] ? { [config.tokenEnv]: process.env[config.tokenEnv] } : {}),
   };
@@ -121,8 +149,31 @@ export async function runVerifier({ project, cell, runDir, candidateDir, config,
       candidateProcess = startProcess(config.startCommand, { cwd: candidateDir, env });
       // A cold Docker build legitimately exceeds a minute. Give the candidate
       // a bounded five-minute startup window, still capped by task timeout.
-      if (config.readinessUrl && !(await waitReady(config.readinessUrl, Math.min(config.timeoutSeconds, 300)))) {
-        return { status: "error", failureOwner: "infrastructure", solvedScore: "NA", durationSeconds: (Date.now() - started) / 1000, error: "candidate readiness timed out" };
+      if (config.readinessUrl) {
+        const readiness = await waitReady(config.readinessUrl, config.timeoutSeconds > 0 ? Math.min(config.timeoutSeconds, 300) : 0, candidateProcess);
+        if (!readiness.ready) {
+          const durationSeconds = (Date.now() - started) / 1000;
+          const detail = readiness.output;
+          if (readiness.exited) {
+            const portCollision = /EADDRINUSE|address already in use|port is already allocated/i.test(detail);
+            return {
+              status: "error",
+              failureOwner: portCollision ? "infrastructure" : "candidate",
+              solvedScore: "NA",
+              durationSeconds,
+              error: detail
+                ? `${portCollision ? "candidate startup blocked by host-port collision" : "candidate startup failed"}: ${detail}`
+                : "candidate startup process exited before readiness",
+            };
+          }
+          return {
+            status: "error",
+            failureOwner: "infrastructure",
+            solvedScore: "NA",
+            durationSeconds,
+            error: detail ? `candidate readiness timed out: ${detail}` : "candidate readiness timed out",
+          };
+        }
       }
     }
     const commandResult = await runCommand(config.command, {
@@ -163,9 +214,9 @@ export async function runVerifier({ project, cell, runDir, candidateDir, config,
     };
   } finally {
     if (config.stopCommand) {
-      await runCommand(config.stopCommand, { cwd: candidateDir, env, timeoutSeconds: Math.min(Number(config.timeoutSeconds) || 30, 30) });
+      await runCommand(config.stopCommand, { cwd: candidateDir, env, timeoutSeconds: config.timeoutSeconds > 0 ? Math.min(Number(config.timeoutSeconds), 30) : 0 });
     }
-    if (candidateProcess && !candidateProcess.killed) candidateProcess.kill("SIGTERM");
+    if (candidateProcess && !candidateProcess.killed) stopProcessTree(candidateProcess, "SIGTERM");
     if (releaseLock) releaseLock();
   }
 }