@0dai-dev/cli 4.3.9 → 4.4.0

package/README.md

@@ -86,7 +86,7 @@ Global flags: `--target PATH`, `--version`, `--help`, `--json`, `--quiet`. See `
 
 ## What it does
 
-`0dai init` and `0dai sync` are activation-first. `init` can complete auth and plan activation in one run: browser/OAuth exchange code via `--auth-code`, Team/Pro activation code via `--code` or `--activation-code`, or the interactive OAuth/device-code prompt. After that it binds the project and sends only allowlisted project metadata (file names + package/build manifests) to the API and generates:
+`0dai init` and `0dai sync` are activation-first. `init` can complete auth and plan activation in one run: browser/OAuth exchange code via `--auth-code`, Team/Pro activation code via `--code` or `--activation-code`, or the interactive OAuth/device-code prompt. After that it binds the project and sends only allowlisted project metadata (file names + hashes of package/build manifests — never their contents) to the API and generates:
 
 - `ai/` — manifests, personas, skills, playbooks, delegation policy
 - `.claude/` — settings, agents, hooks, rules
@@ -95,7 +95,7 @@ Global flags: `--target PATH`, `--version`, `--help`, `--json`, `--quiet`. See `
 - `.aider/` — config, agents
 - `AGENTS.md`, `.mcp.json`
 
-Your source code is never sent. Only file names and package/build manifests.
+Your source code is never sent. Only file names and hashes of package/build manifests — never their contents.
 
 ## Privacy
 
@@ -105,7 +105,7 @@ Local activation and experience records stay on your machine: `ai/meta/telemetry
 
 Cursor and Copilot are editors. They help inside one coding session. 0dai writes a project layer that Claude Code, Codex, OpenCode, Gemini, and Aider can all read. The point is not another autocomplete box; it is one manifest, one set of agent roles, one task queue, and one health check for the repo.
 
-A fresh `0dai init` turns a repo into an AI-ready workspace. It records stack detection, safe project commands, agent preferences, MCP config, and delegation policy under `ai/`, then writes native files such as `AGENTS.md` and `.mcp.json`. Your source stays local; only file names and package/build manifests go to the API.
+A fresh `0dai init` turns a repo into an AI-ready workspace. It records stack detection, safe project commands, agent preferences, MCP config, and delegation policy under `ai/`, then writes native files such as `AGENTS.md` and `.mcp.json`. Your source stays local; only file names and hashes of package/build manifests go to the API — never their contents.
 
 0dai is useful when work needs more than one model or more than one sitting. You can ask for a backlog item with `0dai run "add password reset tests"`, check the queue with `0dai swarm status`, and continue from the same project facts in another agent CLI. Cursor or Copilot can still be your editor; 0dai keeps the repo-level context and task state outside the editor.
 
@@ -113,7 +113,7 @@ The first five minutes are direct: run `0dai init`, run `0dai doctor`, then try
 
 ## Free-tier examples
 
-On the free tier you get ≈5 backlog tasks/day. Example: in one day you might ask 0dai to split and queue these tasks:
+On the free tier you get 1 swarm task/day — an activation teaser (Pro lifts this to 50/day). Enough for one daily cleanup pass; pick a task to queue, for example:
 
 - Write missing tests for the login form.
 - Add empty-state copy to the dashboard.
@@ -121,7 +121,7 @@ On the free tier you get ≈5 backlog tasks/day. Example: in one day you might a
 - Draft a PR checklist from the files changed.
 - Summarize today's `ai/swarm/done` tasks for standup.
 
-Each task can become one or more agent prompts, so the exact count depends on task size. Treat the free tier as enough for a daily cleanup pass; Pro is for larger task queues, graph sync with edges, and session roaming across projects.
+Each backlog item splits into one or more agent prompts. The free tier's 1 task/day suits a daily cleanup pass; Pro (50/day) is for larger task queues, graph sync with edges, and session roaming across projects.
 
 ## Links
 

package/bin/0dai.js

@@ -213,7 +213,7 @@ function printHelp() {
   console.log("  0dai doctor                    # verify health and drift");
   console.log("");
   console.log("Start (first 5 minutes):");
-  console.log("  init           Create ai/ layer + MCP [--local] [--dry-run] [--minimal]");
+  console.log("  init           Create ai/ layer + MCP [--local] [--dry-run] [--minimal] [--template <stack>]");
   console.log("  doctor         Check health, credentials, and drift [--drift] [--security]");
   console.log("  status         Show maturity, swarm, and session state [--json]");
   console.log("  quickstart     Run auth, init, doctor, and status checks in order");

package/lib/commands/experience.js

@@ -17,11 +17,12 @@ function resolvePythonScript(target, name) {
 }
 
 function printExperienceHelp() {
-  console.log("Usage: 0dai experience [list|stats|record-json|sync|warnings|dismiss]");
+  console.log("Usage: 0dai experience [list|stats|report|record-json|sync|warnings|dismiss]");
   console.log("");
   console.log("Commands:");
   console.log("  list         Show recent local experience events");
   console.log("  stats        Summarize local experience events");
+  console.log("  report       What your agents learned about this repo over N days [--period 30d] [--days N]");
   console.log("  record-json  Record one JSON payload through the repo experience helper");
   console.log("  sync         Sync eligible events when the repo helper permits it");
   console.log("  warnings     Show anti-pattern warnings");
@@ -61,6 +62,12 @@ function cmdExperience(target, sub, args) {
     if (periodIdx >= 0 && args[periodIdx + 1]) forwarded.push("--period", args[periodIdx + 1]);
     const byIdx = args.indexOf("--by");
     if (byIdx >= 0 && args[byIdx + 1]) forwarded.push("--by", args[byIdx + 1]);
+  } else if (command === "report") {
+    if (args.includes("--json")) forwarded.push("--json");
+    const periodIdx = args.indexOf("--period");
+    if (periodIdx >= 0 && args[periodIdx + 1]) forwarded.push("--period", args[periodIdx + 1]);
+    const daysIdx = args.indexOf("--days");
+    if (daysIdx >= 0 && args[daysIdx + 1]) forwarded.push("--days", args[daysIdx + 1]);
   } else if (command === "sync") {
     if (args.includes("--json")) forwarded.push("--json");
     const limitIdx = args.indexOf("--limit");

package/lib/commands/init.js

@@ -413,11 +413,31 @@ async function cmdProjectBind(target, args = []) {
 //   files        — { relPath: content } the offline path would write
 //   agentTargets — [{ cli, files: [...] }] the per-CLI config paths a full
 //                  (authenticated) `0dai init` would manage for each detected CLI
-function buildLocalDryRunPreview(target) {
+// --template <stack> (#3931): let the user DECLARE the stack so a fresh repo gets a
+// stack-labeled starter ai/ layer without relying on detection — removes the
+// "empty ai/ / stack: unknown" first-run barrier (TTFV). Canonical stacks mirror
+// detectStackHint's vocabulary; common aliases are accepted.
+const TEMPLATE_ALIASES = {
+  next: "nextjs", nextjs: "nextjs",
+  fastapi: "python-service", python: "python-service", "python-service": "python-service",
+  go: "go-service", golang: "go-service", "go-service": "go-service",
+  flutter: "flutter",
+  rn: "react-native", expo: "react-native", "react-native": "react-native",
+  express: "backend-api", node: "backend-api", "backend-api": "backend-api",
+  ml: "data-ml", "data-ml": "data-ml",
+  react: "frontend", vue: "frontend", frontend: "frontend",
+};
+const TEMPLATE_CHOICES = [...new Set(Object.values(TEMPLATE_ALIASES))].sort();
+function resolveTemplateStack(raw) {
+  const key = String(raw || "").trim().toLowerCase();
+  return TEMPLATE_ALIASES[key] || "";
+}
+
+function buildLocalDryRunPreview(target, templateStack = "") {
   const metadata = collectMetadata(target);
   const { projectFiles, manifestContents, clis } = metadata;
   const projectName = inferProjectName(target, manifestContents);
-  const stack = detectStackHint(projectFiles, manifestContents);
+  const stack = templateStack || detectStackHint(projectFiles, manifestContents);
 
   // Mirror the offline generator (lib/wizard.js stepGenerate) so the preview
   // matches what `0dai init --local` writes without auth — no fabricated bodies.
@@ -454,11 +474,11 @@ function buildLocalDryRunPreview(target) {
 // preview to stdout and returns. Writes nothing to disk and makes no network
 // calls. This is the only path that bypasses the auth/license preflight, and
 // only when BOTH --local AND --dry-run are set (see cmdInit).
-function cmdInitLocalDryRun(target) {
-  const { projectName, stack, clis, files, agentTargets } = buildLocalDryRunPreview(target);
+function cmdInitLocalDryRun(target, templateStack = "") {
+  const { projectName, stack, clis, files, agentTargets } = buildLocalDryRunPreview(target, templateStack);
   log(`local dry-run: no account or network needed`);
   console.log(`  project: ${projectName}`);
-  console.log(`  stack: ${stack}`);
+  console.log(`  stack: ${stack}${templateStack ? " (declared via --template)" : ""}`);
   console.log(`  agent CLIs detected: ${clis.length ? clis.join(", ") : "none"}`);
   console.log("");
   const names = Object.keys(files);
@@ -487,12 +507,26 @@ async function cmdInit(target, args = []) {
   const noWizard = args.includes("--no-wizard");
   const localMode = args.includes("--local");
 
+  // --template <stack> (#3931): declare the stack for the offline/local scaffold so a
+  // fresh repo gets a stack-labeled starter instead of "stack: unknown". Validated
+  // against the canonical stack set (aliases accepted); applies to the --local paths.
+  const templateIdx = args.indexOf("--template");
+  let templateStack = "";
+  if (templateIdx >= 0) {
+    const raw = templateIdx + 1 < args.length ? args[templateIdx + 1] : "";
+    templateStack = resolveTemplateStack(raw);
+    if (!templateStack) {
+      log(`unknown --template '${raw || "(missing)"}'. Valid: ${TEMPLATE_CHOICES.join(", ")}`);
+      return;
+    }
+  }
+
   // Offline preview: `0dai init --local --dry-run` renders configs in memory,
   // prints them, and returns. Bypasses the auth/license/server preflight ONLY
   // when BOTH flags are present (issue #4475). Plain --dry-run (server plan)
   // and plain --local (wizard, writes) are unchanged.
   if (localMode && dryRun) {
-    cmdInitLocalDryRun(target);
+    cmdInitLocalDryRun(target, templateStack);
     return;
   }
 
@@ -552,7 +586,7 @@ async function cmdInit(target, args = []) {
   }
   if (localMode) {
     const { runWizard } = require("../wizard");
-    const result = await runWizard(target, { forceLocal: true });
+    const result = await runWizard(target, { forceLocal: true, stack: templateStack });
     if (result.completed) {
       ensureRuntimeGitignore(target);
       await runMcpBootstrap(target, args);
@@ -1154,6 +1188,8 @@ module.exports = {
   cmdSync,
   cmdProjectBind,
   buildLocalDryRunPreview,
+  resolveTemplateStack,
+  TEMPLATE_CHOICES,
   cmdInitLocalDryRun,
   buildLocalSyncPreview,
   runMcpBootstrap,

package/lib/commands/run.js

@@ -10,10 +10,13 @@ const {
 const { recordActivationFirstTask } = require("../utils/activation_telemetry");
 
 function printRunHelp() {
-  console.log(`Usage: 0dai run <goal> [--dry-run] [--dry-cost] [--max-cost N] [--agent claude|codex|gemini] [--provider deepseek|gemini-direct|codex|claude-opus]`);
+  console.log(`Usage: 0dai run <goal> [--now] [--dry-run] [--dry-cost] [--max-cost N] [--agent claude|codex|gemini] [--provider deepseek|gemini-direct|codex|claude-opus]`);
   console.log(`  Example: 0dai run "add dark mode to settings page"`);
-  console.log(`  Example: 0dai run "fix login bug" --dry-cost`);
+  console.log(`  Example: 0dai run "fix login bug" --now          # execute locally + print a scored receipt`);
+  console.log(`  Example: 0dai run "refactor auth" --dry-cost`);
   console.log(`  Example: 0dai run "refactor auth" --max-cost 0.50`);
+  console.log(`  --now (alias --execute) runs the assigned agent CLI on this repo right now`);
+  console.log(`  (it may modify files); without it, tasks are only queued for ' 0dai watch '.`);
 }
 
 function isRunHelpRequest(goal, args = []) {
@@ -28,6 +31,7 @@ async function cmdRun(goal, target, args = []) {
 
   const dryRun = args.includes("--dry-run");
   const dryCost = args.includes("--dry-cost");
+  const now = args.includes("--now") || args.includes("--execute");
   const agentIdx = args.indexOf("--agent");
   const agentOverride = agentIdx >= 0 ? args[agentIdx + 1] : null;
   const providerIdx = args.indexOf("--provider");
@@ -102,6 +106,7 @@ async function cmdRun(goal, target, args = []) {
   try { fs.mkdirSync(queueDir, { recursive: true }); } catch {}
 
   const created = [];
+  const createdEntries = [];
   for (const t of tasks) {
     const ts = Date.now();
     const rand = Math.random().toString(36).slice(2, 6);
@@ -125,14 +130,30 @@ async function cmdRun(goal, target, args = []) {
     try {
       fs.writeFileSync(path.join(queueDir, `${id}.json`), JSON.stringify(entry, null, 2));
       created.push(id);
+      createdEntries.push(entry);
     } catch (e) { log(`warn: could not write task ${id}: ${e.message}`); }
   }
 
   console.log(`\n  ${T}✓${R} ${created.length} task${created.length === 1 ? "" : "s"} added to swarm queue`);
+
+  const identity = created.length > 0
+    ? shared.buildProjectIdentity(target, shared.collectMetadata(target))
+    : null;
+
+  if (now && createdEntries.length > 0) {
+    runNow(target, queueDir, createdEntries, {
+      goal,
+      maxCost,
+      costEstimateUsd: costEstimate ? costEstimate.totalUsd : null,
+      identity,
+    });
+    return;
+  }
+
   console.log(`  ${D}Monitor: 0dai watch  |  Queue: 0dai swarm status${R}\n`);
+  console.log(`  ${D}Tip: re-run with --now to execute locally and get a scored receipt.${R}\n`);
 
-  if (created.length > 0) {
-    const identity = shared.buildProjectIdentity(target, shared.collectMetadata(target));
+  if (identity) {
     recordActivationFirstTask(target, identity.project_id, {
       outcome: "task_queued",
       task_count: created.length,
@@ -140,6 +161,66 @@ async function cmdRun(goal, target, args = []) {
   }
 }
 
+// Execute the just-queued tasks locally (synchronous), emit a scored receipt,
+// move drained task files queue→done, and record the executed activation outcome.
+function runNow(target, queueDir, entries, { goal, maxCost, costEstimateUsd, identity }) {
+  const { drainTasks } = require("../run/local_executor");
+  const { buildReceipt, writeReceipt, renderReceipt } = require("../run/scored_receipt");
+
+  console.log(
+    `\n  ${T}Executing locally${R} ${D}(--now)${R} — running the assigned agent on this`
+    + ` repo now; it may modify files.\n`,
+  );
+
+  const results = drainTasks(entries, {
+    cwd: target,
+    budgetUsd: maxCost != null ? maxCost : undefined,
+    defaultAgent: entries[0] && entries[0].assigned_to,
+  });
+
+  const runId = `run-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+  const receipt = buildReceipt({
+    runId,
+    goal,
+    results,
+    costEstimateUsd,
+    agent: entries[0] && entries[0].assigned_to,
+  });
+  const file = writeReceipt(target, receipt);
+  console.log(renderReceipt(receipt, { T, R, D }));
+  if (file) {
+    console.log(`  ${D}receipt: ${path.relative(target, file)}${R}\n`);
+  } else {
+    log(`warn: could not persist run receipt to ai/meta/receipts/${runId}.json`);
+  }
+
+  // Move drained task files queue→done so `0dai watch` / `status` stay consistent.
+  const doneDir = path.join(target, "ai", "swarm", "done");
+  try { fs.mkdirSync(doneDir, { recursive: true }); } catch {}
+  for (const r of results) {
+    if (!r.taskId) continue;
+    const src = path.join(queueDir, `${r.taskId}.json`);
+    try {
+      const entry = JSON.parse(fs.readFileSync(src, "utf8"));
+      entry.status = r.status === "pass" ? "done"
+        : r.status === "noop" ? "noop"
+        : r.status === "skipped" ? "queued" : "failed";
+      entry.run_id = runId;
+      entry.result = { status: r.status, exit_code: r.exitCode, reason: r.reason, duration_ms: r.durationMs };
+      if (r.status === "skipped") continue; // leave only skipped tasks queued for a retry
+      fs.writeFileSync(path.join(doneDir, `${r.taskId}.json`), JSON.stringify(entry, null, 2));
+      fs.unlinkSync(src);
+    } catch { /* best-effort */ }
+  }
+
+  if (identity) {
+    recordActivationFirstTask(target, identity.project_id, {
+      outcome: receipt.status === "pass" ? "executed_pass" : "executed_fail",
+      task_count: entries.length,
+    });
+  }
+}
+
 function printCostPreview(costEstimate) {
   console.log(`\n  ${T}Cost preview${R} (estimate):\n`);
   costEstimate.tasks.forEach((row, index) => {

package/lib/python/experience_pipeline.py

@@ -1082,6 +1082,73 @@ def cmd_sync(args: argparse.Namespace) -> int:
     return 0 if result.get("ok") or result.get("skipped") else 1
 
 
+def format_report(stats: dict, recent: list[dict]) -> str:
+    """End-user 'what your agents learned about this repo over N days' summary (#3932)."""
+    s = stats.get("summary") or {}
+    period = s.get("period", "")
+    event_count = int(s.get("event_count", 0))
+    task_count = int(s.get("task_count", 0))
+    sr = int(round((s.get("success_rate") or 0) * 100))
+    lines = [f"What your agents learned — last {period}", ""]
+    lines.append(
+        f"  {event_count} event(s) · {task_count} task(s) · "
+        f"{int(s.get('success_count', 0))} ✅ / {int(s.get('failure_count', 0))} ❌ "
+        f"({sr}% success) · ${float(s.get('total_cost', 0)):.2f} spent"
+    )
+    if not task_count:
+        lines += ["", "  No task experiences recorded yet — run agents on swarm tasks to build history."]
+        return "\n".join(lines)
+
+    def _top(group_key: str, label: str) -> None:
+        groups = stats.get(group_key) or {}
+        ranked = sorted(groups.items(), key=lambda kv: -int(kv[1].get("count", 0)))[:5]
+        if not ranked:
+            return
+        lines.append("")
+        lines.append(f"  {label}:")
+        for name, m in ranked:
+            lines.append(
+                f"    {str(name):<16} {int(m.get('count', 0)):>3} task(s) · "
+                f"{int(round((m.get('success_rate') or 0) * 100))}% success"
+            )
+
+    _top("by_task_type", "Top work")
+    _top("by_agent", "By agent")
+
+    recs = s.get("recommendations") or []
+    if recs:
+        lines.append("")
+        lines.append("  Learned:")
+        for r in recs:
+            lines.append(f"    • {r}")
+
+    if recent:
+        lines.append("")
+        lines.append("  Recent:")
+        for ev in recent[:5]:
+            task = ev.get("task") or {}
+            goal = sanitize_text(task.get("goal") or ev.get("event_type") or "", limit=40) or "—"
+            result = str(task.get("result") or "")
+            mark = "✅" if result in SUCCESS_RESULTS else ("❌" if result in FAIL_RESULTS else "•")
+            ts = str(ev.get("timestamp") or "")[:10]
+            lines.append(f"    {ts} {mark} {goal}")
+
+    lines += ["", "  Anti-pattern warnings: 0dai experience warnings"]
+    return "\n".join(lines)
+
+
+def cmd_report(args: argparse.Namespace) -> int:
+    target = _detect_target(args.target)
+    period = f"{args.days}d" if getattr(args, "days", "") else args.period
+    stats = compute_stats(target, period=period, by="all")
+    recent = load_events(target, since=period, limit=8, include_archive=True)
+    if args.json:
+        print(json.dumps({"report": stats, "recent": recent[:8]}, indent=2, ensure_ascii=False))
+    else:
+        print(format_report(stats, recent))
+    return 0
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="0dai experience", description="Structured experience event pipeline.")
     sub = parser.add_subparsers(dest="command")
@@ -1103,6 +1170,13 @@ def build_parser() -> argparse.ArgumentParser:
     stats_parser.add_argument("--json", action="store_true")
     stats_parser.set_defaults(func=cmd_stats)
 
+    report_parser = sub.add_parser("report")
+    report_parser.add_argument("--target", default=".")
+    report_parser.add_argument("--period", default="30d")
+    report_parser.add_argument("--days", default="", help="shorthand for --period <N>d")
+    report_parser.add_argument("--json", action="store_true")
+    report_parser.set_defaults(func=cmd_report)
+
     record_parser = sub.add_parser("record-json")
     record_parser.add_argument("--target", default=".")
     record_parser.add_argument("--payload", default="")

package/lib/run/local_executor.js

@@ -0,0 +1,223 @@
+"use strict";
+
+// Local synchronous task executor for `0dai run --now`.
+//
+// The keystone of activation: `0dai run` decomposes a goal and queues tasks,
+// but with `--now` it ALSO drains those tasks to completion *locally* — by
+// shelling out to the user's already-installed agent CLI (claude/codex/...) in
+// a single-shot headless invocation. It deliberately does NOT touch the
+// tmux/swarm-runner fleet (that path is for the multi-agent queue drain and is
+// infrastructure the npm-only audience does not have). A fresh `npm i -g`
+// user with `claude` on PATH gets a real completed task + a scored receipt.
+//
+// Invocation templates mirror scripts/spawn_subagent.sh — the authoritative
+// pattern for how 0dai drives each agent CLI non-interactively.
+
+const cp = require("child_process");
+
+const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000; // 15 min per task
+const OUTPUT_TAIL_CHARS = 2000;
+
+// Build the headless single-shot command for an agent. Returns null for agents
+// without a known non-interactive form (caller treats this as "skipped").
+function buildInvocation(agent, prompt, opts = {}) {
+  const budget = Number.isFinite(opts.budgetUsd) ? opts.budgetUsd : null;
+  switch (agent) {
+    case "claude":
+      return {
+        bin: "claude",
+        args: [
+          "--print",
+          "--permission-mode", "auto",
+          ...(budget != null ? ["--max-budget-usd", String(budget)] : []),
+          prompt,
+        ],
+      };
+    case "codex":
+      return {
+        bin: "codex",
+        args: ["exec", "--skip-git-repo-check", "--full-auto", prompt],
+      };
+    case "gemini":
+      // gemini --approval-mode enum is default|auto_edit|yolo|plan ('auto' is
+      // rejected). yolo = auto-approve all tools (write-capable), the mode a
+      // headless task needs to actually make changes.
+      return { bin: "gemini", args: ["--approval-mode", "yolo", "-p", prompt] };
+    case "opencode":
+      return { bin: "opencode", args: ["run", prompt] };
+    case "qoder":
+      return {
+        bin: "qodercli",
+        args: ["-p", prompt, "--yolo", "--output-format", "json"],
+      };
+    default:
+      return null;
+  }
+}
+
+// Compose the instruction handed to the agent. Grounded in the decomposed task
+// plus the original goal so the agent has the same context the queue entry has.
+function buildPrompt(task) {
+  const ctx = (task && task.context) || {};
+  const lines = [];
+  if (ctx.goal) lines.push(`Goal: ${ctx.goal}`);
+  lines.push(`Task: ${task.title || "(untitled)"}`);
+  if (task.description) lines.push("", task.description);
+  lines.push(
+    "",
+    "Make the change in this repository now. Keep the diff focused on this task.",
+    "When finished, print a one-line summary of what you changed.",
+  );
+  return lines.join("\n");
+}
+
+// Default command runner — a thin wrapper over spawnSync so tests can inject a
+// fake. Signature: runner(bin, args, { cwd, timeoutMs }) -> spawnSync-like result.
+function defaultRunner(bin, args, opts = {}) {
+  return cp.spawnSync(bin, args, {
+    cwd: opts.cwd,
+    encoding: "utf8",
+    timeout: opts.timeoutMs || DEFAULT_TIMEOUT_MS,
+    maxBuffer: 32 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+
+// Snapshot of the repo's uncommitted state, used to tell whether an agent run
+// actually changed anything. Returns a comparable token, or null when we can't
+// tell (no git / not a repo) — callers must treat null as "unknown", never as
+// "no change". Injectable so tests stay hermetic.
+function defaultChangeProbe(cwd) {
+  try {
+    const r = cp.spawnSync("git", ["status", "--porcelain"], {
+      cwd,
+      encoding: "utf8",
+      timeout: 5000,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    if (!r || r.status !== 0) return null;
+    return r.stdout || "";
+  } catch {
+    return null;
+  }
+}
+
+// Is `bin` resolvable on PATH? Uses the same injected runner so tests stay hermetic.
+function agentInstalled(bin, runner, opts = {}) {
+  if (opts.skipInstallCheck) return true;
+  try {
+    const r = runner("sh", ["-c", `command -v ${bin} >/dev/null 2>&1`], {
+      cwd: opts.cwd,
+      timeoutMs: 5000,
+    });
+    return !!r && r.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+function tail(text) {
+  if (!text) return "";
+  const s = String(text);
+  return s.length > OUTPUT_TAIL_CHARS ? s.slice(-OUTPUT_TAIL_CHARS) : s;
+}
+
+// Execute a single queued task locally. Pure except for the injected runner.
+// Result: { taskId, agent, status: "pass"|"fail"|"skipped", exitCode, durationMs,
+//           reason, command, outputTail }.
+function executeTask(task, opts = {}) {
+  const runner = opts.runner || defaultRunner;
+  const agent = task.assigned_to || opts.defaultAgent || "claude";
+  const taskId = task.id || null;
+
+  const invocation = buildInvocation(agent, buildPrompt(task), {
+    budgetUsd: opts.budgetUsd,
+  });
+  if (!invocation) {
+    return {
+      taskId, agent, status: "skipped", exitCode: null, durationMs: 0, changed: null,
+      reason: `no headless invocation known for agent '${agent}'`,
+      command: null, outputTail: "",
+    };
+  }
+
+  const command = `${invocation.bin} ${invocation.args.join(" ")}`;
+  if (!agentInstalled(invocation.bin, runner, { cwd: opts.cwd, skipInstallCheck: opts.skipInstallCheck })) {
+    return {
+      taskId, agent, status: "skipped", exitCode: null, durationMs: 0, changed: null,
+      reason: `'${invocation.bin}' not found on PATH — install it or run the task yourself`,
+      command, outputTail: "",
+    };
+  }
+
+  const changeProbe = opts.changeProbe || defaultChangeProbe;
+  const before = changeProbe(opts.cwd);
+
+  const started = Date.now();
+  let r;
+  try {
+    r = runner(invocation.bin, invocation.args, { cwd: opts.cwd, timeoutMs: opts.timeoutMs });
+  } catch (e) {
+    return {
+      taskId, agent, status: "fail", exitCode: null, durationMs: Date.now() - started,
+      changed: null, reason: `executor error: ${e.message}`, command, outputTail: "",
+    };
+  }
+  const durationMs = Date.now() - started;
+
+  const after = changeProbe(opts.cwd);
+  const changed = (before == null || after == null) ? null : (before !== after);
+
+  // Timeout / signal kill → fail. spawnSync sets .error on timeout and may set .signal.
+  if (r && (r.error || r.signal)) {
+    const why = r.error ? r.error.message : `killed by signal ${r.signal}`;
+    return {
+      taskId, agent, status: "fail", exitCode: r.status ?? null, durationMs, changed,
+      reason: `agent did not complete: ${why}`, command,
+      outputTail: tail(r.stderr || r.stdout),
+    };
+  }
+
+  // Exit 0 is necessary but NOT sufficient: an agent can exit 0 having changed
+  // nothing. When we can tell (git repo), a clean exit with no file change is a
+  // "noop", never a success — the receipt must not claim a task was done when
+  // the repo is untouched. When we can't tell (changed === null) fall back to
+  // the exit code.
+  const exitCode = r ? r.status : null;
+  let status;
+  let reason;
+  if (exitCode !== 0) {
+    status = "fail";
+    reason = `agent exited ${exitCode}${changed === true ? " (repo changed)" : ""}`;
+  } else if (changed === false) {
+    status = "noop";
+    reason = "agent exited 0 but made no file changes";
+  } else {
+    status = "pass";
+    reason = changed === true ? "agent exited 0; repo changed" : "agent exited 0";
+  }
+  return {
+    taskId, agent, status, exitCode, durationMs, changed, reason,
+    command, outputTail: tail((r && (r.stdout || r.stderr)) || ""),
+  };
+}
+
+// Drain a list of queued task entries sequentially (synchronous, local).
+function drainTasks(tasks, opts = {}) {
+  const results = [];
+  for (const task of tasks) {
+    results.push(executeTask(task, opts));
+  }
+  return results;
+}
+
+module.exports = {
+  buildInvocation,
+  buildPrompt,
+  executeTask,
+  drainTasks,
+  agentInstalled,
+  defaultRunner,
+  defaultChangeProbe,
+  DEFAULT_TIMEOUT_MS,
+};

package/lib/run/scored_receipt.js

@@ -0,0 +1,136 @@
+"use strict";
+
+// Scored run-receipt — the canonical artifact a completed `0dai run --now`
+// produces: a verdict about what the run actually did, persisted as JSON and
+// printed inline. Honest by construction — a clean exit that changed nothing is
+// a "noop", not a pass — so the number is a fair summary, not a success
+// rubber-stamp. (Caveat: change detection needs a git repo; outside one the
+// outcome falls back to the agent's exit code.) Distinct from
+// `lib/commands/receipt.js`, which renders a per-session OG *image* to
+// ~/.0dai/receipts/; this writes a structured per-run JSON to
+// ai/meta/receipts/<run-id>.json.
+
+const fs = require("fs");
+const path = require("path");
+
+const SCHEMA = "0dai.run-receipt/1";
+
+function receiptsDir(target) {
+  return path.join(target, "ai", "meta", "receipts");
+}
+
+function receiptPath(target, runId) {
+  return path.join(receiptsDir(target), `${runId}.json`);
+}
+
+// Completion score, 0-100. Transparent and honest: the share of *executed*
+// tasks that passed. "noop" (ran clean but changed nothing) and "fail" both
+// count in the denominator but not as passes, so a run that touched nothing
+// can never score 100. Skipped tasks (agent not installed / unsupported) are
+// excluded entirely and reported separately, so the number never silently
+// rewards a run where nothing actually ran.
+function scoreRun(results) {
+  const passed = results.filter((r) => r.status === "pass").length;
+  const failed = results.filter((r) => r.status === "fail").length;
+  const noop = results.filter((r) => r.status === "noop").length;
+  const executed = passed + failed + noop;
+  return executed > 0 ? Math.round((100 * passed) / executed) : 0;
+}
+
+// Overall verdict for the run. Only an all-pass run is "pass"; a run with no
+// passes at all is "fail"; anything mixed (some pass + any fail/noop/skip) is
+// "partial". An empty run is "fail" (nothing succeeded).
+function overallStatus(results) {
+  if (!results.length) return "fail";
+  const passed = results.filter((r) => r.status === "pass").length;
+  const failed = results.filter((r) => r.status === "fail").length;
+  const noop = results.filter((r) => r.status === "noop").length;
+  const skipped = results.filter((r) => r.status === "skipped").length;
+  if (passed > 0 && failed === 0 && noop === 0 && skipped === 0) return "pass";
+  if (passed === 0) return "fail";
+  return "partial";
+}
+
+function buildReceipt({ runId, goal, results, costEstimateUsd = null, agent = null }) {
+  const passed = results.filter((r) => r.status === "pass").length;
+  const failed = results.filter((r) => r.status === "fail").length;
+  const noop = results.filter((r) => r.status === "noop").length;
+  const skipped = results.filter((r) => r.status === "skipped").length;
+  return {
+    schema: SCHEMA,
+    run_id: runId,
+    goal: goal || "",
+    created_at: new Date().toISOString(),
+    agent: agent || (results[0] && results[0].agent) || null,
+    status: overallStatus(results),
+    score: scoreRun(results),
+    passed,
+    failed,
+    noop,
+    skipped,
+    total: results.length,
+    cost_estimate_usd: costEstimateUsd,
+    tasks: results.map((r) => ({
+      id: r.taskId,
+      agent: r.agent,
+      status: r.status,
+      exit_code: r.exitCode,
+      duration_ms: r.durationMs,
+      changed: r.changed ?? null,
+      reason: r.reason,
+    })),
+  };
+}
+
+// Persist the receipt. Best-effort: returns the path on success, null on failure.
+function writeReceipt(target, receipt) {
+  try {
+    fs.mkdirSync(receiptsDir(target), { recursive: true });
+    const file = receiptPath(target, receipt.run_id);
+    fs.writeFileSync(file, JSON.stringify(receipt, null, 2));
+    return file;
+  } catch {
+    return null;
+  }
+}
+
+// Human-readable inline summary printed at the end of a `--now` run.
+function renderReceipt(receipt, palette = {}) {
+  const T = palette.T || "";
+  const R = palette.R || "";
+  const D = palette.D || "";
+  const mark = receipt.status === "pass" ? "✓" : receipt.status === "fail" ? "✗" : "◐";
+  const lines = [];
+  lines.push("");
+  lines.push(`  ${T}Run receipt${R}  ${D}${receipt.run_id}${R}`);
+  lines.push(
+    `  ${mark} ${receipt.status.toUpperCase()}`
+    + `  score ${receipt.score}/100`
+    + `  (${receipt.passed} passed, ${receipt.failed} failed`
+    + `${receipt.noop ? `, ${receipt.noop} noop` : ""}`
+    + `${receipt.skipped ? `, ${receipt.skipped} skipped` : ""})`,
+  );
+  for (const t of receipt.tasks) {
+    const tm = t.status === "pass" ? "✓"
+      : t.status === "fail" ? "✗"
+      : t.status === "noop" ? "∅" : "–";
+    const dur = t.duration_ms != null ? ` ${Math.round(t.duration_ms / 1000)}s` : "";
+    lines.push(`     ${tm} ${D}${t.id || ""}${R} ${t.reason}${dur}`);
+  }
+  if (receipt.cost_estimate_usd != null) {
+    lines.push(`  ${D}est. cost ~$${receipt.cost_estimate_usd.toFixed(2)}${R}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+module.exports = {
+  SCHEMA,
+  receiptsDir,
+  receiptPath,
+  scoreRun,
+  overallStatus,
+  buildReceipt,
+  writeReceipt,
+  renderReceipt,
+};

package/lib/wizard.js

@@ -278,8 +278,9 @@ function stepNext(mode) {
 async function runWizard(target, options = {}) {
   const forceLocal = Boolean(options.forceLocal);
   if (!isInteractive()) {
-    // Non-interactive: use defaults silently
-    stepGenerate(target, "all", []);
+    // Non-interactive: use defaults silently. A declared --template stack (#3931)
+    // skips detection so the scaffold is stack-labeled instead of "unknown".
+    stepGenerate(target, "all", options.stack ? [options.stack] : []);
     return { completed: true, interactive: false };
   }
 
@@ -306,7 +307,8 @@ async function runWizard(target, options = {}) {
       return { completed: false, interactive: true, cloudRequested: true, agent, mode };
     }
 
-    const stack = await stepDetect(rl, target);
+    // A declared --template stack (#3931) skips interactive detection.
+    const stack = options.stack ? [options.stack] : await stepDetect(rl, target);
     if (aborted) return { completed: false };
 
     stepGenerate(target, agent, stack);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0dai-dev/cli",
-  "version": "4.3.9",
+  "version": "4.4.0",
   "description": "One config layer for seven AI coding agents \u2014 Claude Code, Codex, OpenCode, Gemini, Aider, Qoder, Cursor",
   "bin": {
     "0dai": "./bin/0dai.js"