@felixdotgo/aidlc-kit 0.2.0 → 0.3.0

package/dist/assets/.agents/aidlc/scripts/lib/task-runtime.mjs

@@ -0,0 +1,97 @@
+/**
+ * Per-task operational data lives under the task's own directory:
+ *
+ *   .agents/data/tasks/<taskId>/runtime/
+ *     assignments.json      local worker claims (`assignment-store.mjs`)
+ *     assignments.lock      short mutex around one assignments read-modify-write
+ *     events.jsonl (+ .1)   the task's event history (`loop-stream.mjs`)
+ *     run.json              the loop run record (`loop-runtime.mjs`)
+ *     intake.json           the loop intake record (`loop-intake.mjs`)
+ *     requirement.md        the intake requirement text
+ *     workers/              container index and raw output (`loop-worker-log.mjs`)
+ *
+ * The task directory root keeps review artifacts only; `.agents/data/loop/`
+ * keeps daemon/process state (daemon lock and log, the global event sidecar,
+ * task leases). The same layout serves the no-loop workflow, the local loop,
+ * and fleet, so every reader finds task data without knowing which mode wrote
+ * it. `runtime/` is operational: never committed, handed off, or clean-checked
+ * (`isLoopOperationalPath` in loop-git.mjs).
+ *
+ * Older versions kept these files under `.agents/data/loop/` (assignments,
+ * events, `<task>.json` run record) and at the task directory root
+ * (`loop-intake.json`, `requirement.md`). `legacyTaskRuntimePath` names those
+ * locations so readers fall back to them and `task-runtime-migrate.mjs` moves
+ * them once.
+ */
+import { lstatSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+/** Runtime file names and where an older aidlc-kit kept each one (relative to `.agents/data`). */
+export const TASK_RUNTIME_FILES = Object.freeze({
+  "assignments.json": (taskId) => ["loop", "assignments", `${taskId}.json`],
+  "assignments.lock": (taskId) => ["loop", "assignments", `${taskId}.lock`],
+  "events.jsonl": (taskId) => ["loop", "events", `${taskId}.jsonl`],
+  "events.jsonl.1": (taskId) => ["loop", "events", `${taskId}.jsonl.1`],
+  "run.json": (taskId) => ["loop", `${taskId}.json`],
+  "intake.json": (taskId) => ["tasks", taskId, "loop-intake.json"],
+  "requirement.md": (taskId) => ["tasks", taskId, "requirement.md"],
+});
+
+/** Runtime files that `task-runtime-migrate.mjs` moves (locks are short-lived and expire on their own). */
+export const MIGRATED_TASK_RUNTIME_FILES = Object.freeze(["assignments.json", "events.jsonl", "events.jsonl.1", "run.json", "intake.json", "requirement.md"]);
+
+export const isTaskId = (value) => typeof value === "string" && ID_PATTERN.test(value);
+const safeTaskId = (taskId) => { if (!isTaskId(taskId)) throw new Error(`Invalid task id: ${taskId}`); return taskId; };
+const safeName = (name) => { if (!Object.hasOwn(TASK_RUNTIME_FILES, name)) throw new Error(`Unknown task runtime file: ${name}`); return name; };
+
+/** Throw when `path` exists and is a symlink (a planted link must not redirect reads or writes). */
+const refuseSymlink = (path) => {
+  try { if (lstatSync(path).isSymbolicLink()) throw new Error(`Task runtime path crosses symlink: ${path}`); }
+  catch (error) { if (error?.code !== "ENOENT") throw error; }
+};
+
+/** Join `parts` under `root`, refusing any symlinked component. */
+const safeJoin = (root, parts) => {
+  let path = resolve(root);
+  for (const part of parts) { path = join(path, part); refuseSymlink(path); }
+  return path;
+};
+
+/** `.agents/data/tasks/<taskId>/runtime`, every component checked for symlinks. */
+export function taskRuntimeDir(root, taskId) {
+  return safeJoin(root, [".agents", "data", "tasks", safeTaskId(taskId), "runtime"]);
+}
+
+/** The current location of one runtime file (`name` from TASK_RUNTIME_FILES). */
+export function taskRuntimePath(root, taskId, name) {
+  return safeJoin(root, [".agents", "data", "tasks", safeTaskId(taskId), "runtime", safeName(name)]);
+}
+
+/** Where an older aidlc-kit kept the same runtime file. */
+export function legacyTaskRuntimePath(root, taskId, name) {
+  return safeJoin(root, [".agents", "data", ...TASK_RUNTIME_FILES[safeName(name)](safeTaskId(taskId))]);
+}
+
+/** True when `path` is a regular (non-symlink) file. */
+export const isRegularFile = (path) => {
+  try { const stat = lstatSync(path); return stat.isFile() && !stat.isSymbolicLink(); } catch (error) { if (error?.code === "ENOENT") return false; throw error; }
+};
+
+/** Read location of a runtime file: the current path when it exists, else the
+ * legacy path when that exists, else the current path (for a clean ENOENT). */
+export function resolveTaskRuntimeRead(root, taskId, name) {
+  const current = taskRuntimePath(root, taskId, name);
+  if (isRegularFile(current)) return current;
+  const legacy = legacyTaskRuntimePath(root, taskId, name);
+  return isRegularFile(legacy) ? legacy : current;
+}
+
+/** Create the runtime directory (0700, like the task directory an intake creates) and return it. */
+export function ensureTaskRuntimeDir(root, taskId) {
+  const directory = taskRuntimeDir(root, taskId);
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  refuseSymlink(directory);
+  return directory;
+}

package/dist/assets/.agents/aidlc/scripts/loop-entry.mjs

@@ -6,9 +6,22 @@
  *   intake        create a loop-owned task from a stdin requirement (≤ 8192 bytes) without running it
  *   status        print the canonical task, loop record/checkpoint, and next action
  *   worker-image  build and record a provider worker image
+ *   env           report the daemon environment: providers, env file, each variable's
+ *                 source (shell/file/derived) and missing values; secrets are never
+ *                 printed. `env [root] [--json]`; exits 1 when the daemon could not start.
+ *   leases        list loop leases, locks and claims: who holds what, until when,
+ *                 what it blocks, and how to clear it. Works with any loop mode.
+ *                 `leases [task-id] [root] [--json] [--clear-stale]`; --clear-stale
+ *                 removes only stale/old-corrupt lease, lock and guard files.
+ *   migrate-data  move per-task runtime files of older versions (loop assignments,
+ *                 events, run records, intake) under .agents/data/tasks/<id>/runtime/.
+ *                 `migrate-data [root] [--dry-run] [--json]`; idempotent, never
+ *                 overwrites or deletes (the daemon also runs it at start).
  * Dashboard JSON actions (fleet authority; local dashboards read local state in-process):
  *   tasks | task <id> | gate <id> | resume-task <id> | approve <id> (source on stdin,
- *   reviewer credential only from AIDLC_FLEET_REVIEWER_TOKEN of this process)
+ *   reviewer credential only from AIDLC_FLEET_REVIEWER_TOKEN of this process) |
+ *   feedback <id> (JSON `{ reason, source }` on stdin; keeps the task at its gate
+ *   and never needs the reviewer credential)
  *
  * Positional arguments: [action, taskId, root, mode, provider, tag, title].
  * Gate approval for local tasks stays on the trusted terminal (`loop-gate.mjs`).
@@ -24,11 +37,15 @@ import { runLoopDaemon } from "./lib/loop-daemon.mjs";
 import { streamLog } from "./lib/loop-stream.mjs";
 import * as localSupervisor from "./lib/loop-supervisor-run-local.mjs";
 import { buildWorkerImage, defaultWorkerImageTag, recordWorkerImage } from "./lib/loop-worker-image.mjs";
+import { formatLeases, runLeases } from "./lib/loop-leases.mjs";
+import { migrateAllTaskRuntime } from "./lib/task-runtime-migrate.mjs";
+import { formatLoopEnvReport, loadLoopEnv, publicReport } from "./lib/loop-env.mjs";
+import { callRemoteTool } from "./lib/remote-state-client.mjs";
 
 const [action, taskArg, rootArg, modeArg, providerArg, tagArg, titleArg] = process.argv.slice(2);
 const root = resolve(rootArg || ".");
 const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-const ACTIONS = ["start", "resume", "status", "intake", "tasks", "task", "gate", "resume-task", "approve"];
+const ACTIONS = ["start", "resume", "status", "intake", "tasks", "task", "gate", "resume-task", "approve", "feedback"];
 const readStdin = async (prompt) => {
   if (stdin.isTTY) { const rl = createInterface({ input: stdin, output: stdout }); try { return await rl.question(prompt); } finally { rl.close(); } }
   const chunks = []; for await (const chunk of stdin) { chunks.push(chunk); if (chunks.reduce((n, c) => n + c.length, 0) > 8192) throw new Error("Input exceeds 8192 bytes"); } return Buffer.concat(chunks).toString("utf8");
@@ -36,8 +53,60 @@ const readStdin = async (prompt) => {
 const requireTaskId = () => { if (!ID.test(taskArg ?? "")) throw new Error("Valid task ID required"); return taskArg; };
 const print = (value) => console.log(JSON.stringify(value, null, 2));
 
+/** `leases [task-id] [root] [--json] [--clear-stale]`; empty positionals are skipped. */
+async function runLeasesAction(argv) {
+  const flagSet = new Set(argv.filter((value) => value.startsWith("--")));
+  for (const flag of flagSet) if (!["--json", "--clear-stale"].includes(flag)) throw new Error(`Unknown leases option: ${flag}`);
+  const [taskValue = "", rootValue = ""] = argv.filter((value) => !value.startsWith("--"));
+  if (taskValue && !ID.test(taskValue)) throw new Error("Valid task ID required");
+  const leasesRoot = resolve(rootValue || ".");
+  let config = null;
+  try { config = JSON.parse(readFileSync(join(leasesRoot, ".agents", "config.json"), "utf8")); } catch { config = null; }
+  const env = process.env;
+  const fleetReader = config?.loop?.mode === "fleet" && env.AIDLC_FLEET_URL && env.AIDLC_FLEET_TOKEN && env.AIDLC_FLEET_WORKSPACE
+    ? () => callRemoteTool({ url: env.AIDLC_FLEET_URL, token: env.AIDLC_FLEET_TOKEN }, "fleet_get", { workspace: env.AIDLC_FLEET_WORKSPACE })
+    : undefined;
+  const report = await runLeases({ root: leasesRoot, taskId: taskValue || undefined, clearStale: flagSet.has("--clear-stale"), fleetReader });
+  if (config?.loop?.mode === "fleet" && !fleetReader) report.fleet = { revision: null, entries: [], error: "lead credential not set (AIDLC_FLEET_URL, AIDLC_FLEET_TOKEN, AIDLC_FLEET_WORKSPACE); fleet leases not shown" };
+  if (flagSet.has("--json")) print(report);
+  else console.log(formatLeases(report));
+}
+
+/** `migrate-data [root] [--dry-run] [--json]`: move pre-runtime per-task files under `runtime/`. */
+function runMigrateDataAction(argv) {
+  const flagSet = new Set(argv.filter((value) => value.startsWith("--")));
+  for (const flag of flagSet) if (!["--json", "--dry-run"].includes(flag)) throw new Error(`Unknown migrate-data option: ${flag}`);
+  const [rootValue = ""] = argv.filter((value) => !value.startsWith("--"));
+  const migrateRoot = resolve(rootValue || ".");
+  const result = migrateAllTaskRuntime(migrateRoot, { dryRun: flagSet.has("--dry-run") });
+  if (flagSet.has("--json")) { print({ schemaVersion: 1, root: migrateRoot, ...result }); return; }
+  const verb = result.dryRun ? "would move" : "moved";
+  if (!result.entries.length) { console.log(`Nothing to migrate: every task runtime file is already under .agents/data/tasks/<id>/runtime/ (${migrateRoot})`); return; }
+  for (const entry of result.entries) console.log(`${entry.action === "skipped" ? "skipped" : verb}: ${entry.from} -> ${entry.to}${entry.reason ? ` (${entry.reason})` : ""}`);
+  console.log(`${result.dryRun ? "Would move" : "Moved"} ${result.entries.filter((entry) => entry.action !== "skipped").length} file(s), skipped ${result.skipped}.`);
+}
+
+/** `env [root] [--json]`: the local daemon environment report (no secret values). */
+function runEnvAction(argv) {
+  const flagSet = new Set(argv.filter((value) => value.startsWith("--")));
+  for (const flag of flagSet) if (flag !== "--json") throw new Error(`Unknown env option: ${flag}`);
+  const [rootValue = ""] = argv.filter((value) => !value.startsWith("--"));
+  const envRoot = resolve(rootValue || ".");
+  let config = null;
+  try { config = JSON.parse(readFileSync(join(envRoot, ".agents", "config.json"), "utf8")); } catch { config = null; }
+  const report = publicReport(loadLoopEnv({ root: envRoot, config }));
+  if (flagSet.has("--json")) print(report); else console.log(formatLoopEnvReport(report));
+  if (!report.ok) process.exitCode = 1;
+}
+
 try {
-  if (action === "worker-image") {
+  if (action === "env") {
+    runEnvAction(process.argv.slice(3));
+  } else if (action === "leases") {
+    await runLeasesAction(process.argv.slice(3));
+  } else if (action === "migrate-data") {
+    runMigrateDataAction(process.argv.slice(3));
+  } else if (action === "worker-image") {
     // Build (or rebuild) a worker image without requiring loop configuration.
     const provider = providerArg || "opencode";
     if (!isLoopProvider(provider)) throw new Error("Expected --provider codex, claude, or opencode");
@@ -47,7 +116,7 @@ try {
     console.log(`Built worker image: ${image}`);
     console.log("Recorded worker image; the loop supervisor will use it automatically.");
   } else {
-    if (!ACTIONS.includes(action)) throw new Error("Expected loop start, status, intake, or worker-image");
+    if (!ACTIONS.includes(action)) throw new Error("Expected loop start, status, intake, env, leases, migrate-data, or worker-image");
     const config = JSON.parse(readFileSync(join(root, ".agents", "config.json"), "utf8"));
     const mode = modeArg || config.loop?.mode || "off";
     if (!["local", "fleet"].includes(mode)) throw new Error("Loop mode is off; configure an enabled loop mode first");
@@ -57,6 +126,13 @@ try {
     if (!isLoopProvider(agent) || !Object.keys(workers).length || Object.entries(workers).some(([, value]) => !isLoopProvider(value))) throw new Error("Loop requires a configured lead and worker providers");
     if (action === "resume") throw new Error("loop resume is removed; the daemon auto-resumes actionable tasks — run 'loop start', and re-activate a paused task from the dashboard (resume) or with the task status command");
     if (mode === "local") requireLocalAuthority();
+    if (mode === "local" && action === "start") {
+      // Zero-config start: shell > AIDLC env file > values derived from the providers' own config.
+      const loaded = loadLoopEnv({ root, config });
+      for (const problem of loaded.problems) process.stderr.write(`loop: ${problem.level === "error" ? "error" : "warning"}: ${problem.message}\n`);
+      if (!loaded.ok) throw new Error("environment is incomplete; fix the errors above (check with: aidlc-kit loop env)");
+      Object.assign(process.env, loaded.applied);
+    }
     if (mode === "local" && action === "status") {
       const supervisor = await localSupervisor.createIsolatedLocalSupervisor({ root, taskId: requireTaskId(), agent, workers, workerImages: config.loop?.workerImage, onEvent: streamLog });
       print(await supervisor.status());
@@ -96,6 +172,13 @@ try {
       } else if (action === "approve") {
         const taskId = requireTaskId();
         print(await authority.approve({ taskId, source: (await readStdin("Approval source: ")).trim(), reviewerToken: process.env.AIDLC_FLEET_REVIEWER_TOKEN }));
+      } else if (action === "feedback") {
+        // Human guidance that keeps the task at its current gate; no reviewer credential is involved.
+        const taskId = requireTaskId();
+        let input; try { input = JSON.parse(await readStdin("Feedback JSON: ")); } catch { throw new Error("Feedback must be a JSON object { reason, source }"); }
+        const reason = typeof input?.reason === "string" ? input.reason.trim() : "", source = typeof input?.source === "string" ? input.source.trim() : "";
+        if (!input || typeof input !== "object" || Array.isArray(input) || !reason || !source) throw new Error("Feedback must be a JSON object { reason, source } with non-empty strings");
+        print(await authority.feedback({ taskId, reason, source }));
       }
     }
   }

package/dist/assets/.agents/aidlc/scripts/loop.cmd

@@ -0,0 +1,101 @@
+@echo off
+rem AI-DLC loop launcher (managed by aidlc-kit; upgrades overwrite local edits).
+rem   .agents\aidlc\scripts\loop.cmd [command] [options]
+rem Edit .agents\config.json ("loop") and .agents\loop.env, then run "loop.cmd up".
+rem The script only locates the aidlc-kit CLI and forwards to "aidlc-kit loop <command>";
+rem it never installs or upgrades anything. Local workers need Docker Desktop; the loop is
+rem verified on Linux, so treat native Windows as best effort.
+setlocal
+for %%I in ("%~dp0..\..\..") do set "ROOT=%%~fI"
+
+where node >nul 2>nul
+if errorlevel 1 (
+  echo loop.cmd: Node.js 20.17 or newer is required ^(https://nodejs.org^) 1>&2
+  exit /b 1
+)
+
+set "CMD=%~1"
+rem Options without a command run the default command: "loop.cmd --open" = "loop.cmd up --open".
+if "%CMD%"=="" goto default_cmd
+if /i "%CMD%"=="-h" goto named_cmd
+if /i "%CMD%"=="--help" goto named_cmd
+if "%CMD:~0,1%"=="-" goto default_cmd
+:named_cmd
+shift
+goto args
+:default_cmd
+set "CMD=up"
+:args
+set "ARGS="
+:collect
+if "%~1"=="" goto dispatch
+set ARGS=%ARGS% %1
+shift
+goto collect
+
+:dispatch
+if /i "%CMD%"=="help" goto usage
+if /i "%CMD%"=="-h" goto usage
+if /i "%CMD%"=="--help" goto usage
+if /i "%CMD%"=="check" set "CMD=env"
+if /i "%CMD%"=="logs" goto logs
+for %%C in (up down stop status env) do if /i "%CMD%"=="%%C" goto run
+echo loop.cmd: unknown command: %CMD% 1>&2
+call :usage 1>&2
+exit /b 2
+
+:run
+call :cli loop %CMD% --root "%ROOT%" %ARGS%
+exit /b %ERRORLEVEL%
+
+:cli
+if exist "%ROOT%\node_modules\.bin\aidlc-kit.cmd" (
+  call "%ROOT%\node_modules\.bin\aidlc-kit.cmd" %*
+  goto :eof
+)
+set "RECORDED_CLI="
+for /f "usebackq delims=" %%P in (`node -e "try{const r=require(process.argv[1]);if(typeof r.cli==='string'&&require('fs').statSync(r.cli).isFile())process.stdout.write(r.cli)}catch{}" "%ROOT%\.agents\data\loop\cli.json" 2^>nul`) do set "RECORDED_CLI=%%P"
+if defined RECORDED_CLI (
+  node "%RECORDED_CLI%" %*
+  goto :eof
+)
+where aidlc-kit >nul 2>nul
+if not errorlevel 1 (
+  call aidlc-kit %*
+  goto :eof
+)
+set "VERSION=latest"
+for /f "usebackq delims=" %%V in (`node -p "require(process.argv[1]).packageVersion" "%ROOT%\.agents\aidlc\manifest.json" 2^>nul`) do set "VERSION=%%V"
+where npx >nul 2>nul
+if not errorlevel 1 (
+  echo loop.cmd: aidlc-kit was not found in this project or recorded by init/upgrade; trying npx --no-install ^(if it fails: npm install --save-dev @felixdotgo/aidlc-kit@%VERSION%, or rerun init/upgrade from the package or .tgz you want^) 1>&2
+  call npx --no-install @felixdotgo/aidlc-kit %*
+  goto :eof
+)
+echo loop.cmd: the aidlc-kit CLI was not found: install it in this project ^(npm install --save-dev @felixdotgo/aidlc-kit@%VERSION%^), or rerun init/upgrade from the package or .tgz you want 1>&2
+exit /b 1
+
+:logs
+set "LOG=%ROOT%\.agents\data\loop\daemon.log"
+if exist "%LOG%" goto follow_log
+echo No daemon log yet: "%LOG%"
+exit /b 0
+:follow_log
+powershell -NoProfile -Command "Get-Content -LiteralPath $env:LOG -Tail 200 -Wait"
+exit /b %ERRORLEVEL%
+
+:usage
+echo Usage: .agents\aidlc\scripts\loop.cmd [command] [options]
+echo.
+echo Commands:
+echo   up       check the environment, start the loop daemon, and serve the dashboard (default)
+echo            options: --loop-env PATH  --port 4173  --host 127.0.0.1  --open  --no-ui
+echo   down     stop the dashboard started by "up" and the loop daemon (--now cancels the running turn)
+echo   stop     stop only the loop daemon (--now cancels the running turn)
+echo   status   daemon, dashboard, and environment at a glance (--json)
+echo   check    show providers, the env file, and every variable the loop needs (--json)
+echo   logs     follow the daemon log
+echo   help     show this help
+echo.
+echo Configure .agents\config.json ("loop" section) and .agents\loop.env (model and API keys).
+exit /b 0

package/dist/assets/.agents/aidlc/scripts/loop.sh

@@ -0,0 +1,71 @@
+#!/bin/sh
+# AI-DLC loop launcher (managed by aidlc-kit; upgrades overwrite local edits).
+#
+#   .agents/aidlc/scripts/loop.sh [command] [options]
+#
+# Edit .agents/config.json ("loop") and .agents/loop.env, then run `loop.sh up`.
+# The script only locates the aidlc-kit CLI and forwards to `aidlc-kit loop <command>`;
+# it never installs or upgrades anything.
+set -eu
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+ROOT=$(CDPATH= cd -- "$SCRIPT_DIR/../../.." && pwd)
+
+usage() {
+  cat <<'EOF'
+Usage: .agents/aidlc/scripts/loop.sh [command] [options]
+
+Commands:
+  up       check the environment, start the loop daemon, and serve the dashboard (default)
+           options: --loop-env PATH  --port 4173  --host 127.0.0.1  --open  --no-ui
+  down     stop the dashboard started by `up` and the loop daemon (--now cancels the running turn)
+  stop     stop only the loop daemon (--now cancels the running turn)
+  status   daemon, dashboard, and environment at a glance (--json)
+  check    show providers, the env file, and every variable the loop needs (--json)
+  logs     follow the daemon log
+  help     show this help
+
+Configure:
+  .agents/config.json   "loop": { "mode": "local", "agents": { "lead": "<provider>", "workers": { "worker-a": "<provider>" } } }
+  .agents/loop.env      model and API keys (git-ignored); values your tools already store are detected
+EOF
+}
+
+command -v node >/dev/null 2>&1 || { echo "loop.sh: Node.js 20.17 or newer is required (https://nodejs.org)" >&2; exit 1; }
+
+# The installed workflow version, so hints name the matching package.
+VERSION=$(node -p 'require(process.argv[1]).packageVersion' "$ROOT/.agents/aidlc/manifest.json" 2>/dev/null || echo latest)
+INSTALL_HINT="install it in this project (npm install --save-dev @felixdotgo/aidlc-kit@$VERSION), or rerun init/upgrade from the package or .tgz you want"
+# The CLI that installed this workflow (recorded by init/upgrade), if it still exists.
+RECORDED_CLI=$(node -e 'try{const r=require(process.argv[1]);if(typeof r.cli==="string"&&require("fs").statSync(r.cli).isFile())process.stdout.write(r.cli)}catch{}' "$ROOT/.agents/data/loop/cli.json" 2>/dev/null || true)
+
+run_cli() {
+  if [ -x "$ROOT/node_modules/.bin/aidlc-kit" ]; then exec "$ROOT/node_modules/.bin/aidlc-kit" "$@"; fi
+  if [ -n "$RECORDED_CLI" ]; then exec node "$RECORDED_CLI" "$@"; fi
+  if command -v aidlc-kit >/dev/null 2>&1; then exec aidlc-kit "$@"; fi
+  if command -v npx >/dev/null 2>&1; then
+    echo "loop.sh: aidlc-kit was not found in this project or recorded by init/upgrade; trying npx --no-install (if it fails: $INSTALL_HINT)" >&2
+    exec npx --no-install @felixdotgo/aidlc-kit "$@"
+  fi
+  echo "loop.sh: the aidlc-kit CLI was not found: $INSTALL_HINT" >&2
+  exit 1
+}
+
+# Options without a command run the default command: `loop.sh --open` = `loop.sh up --open`.
+case "${1:-up}" in
+  -h|--help) cmd=help; shift ;;
+  -*) cmd=up ;;
+  *) cmd=${1:-up}; [ $# -gt 0 ] && shift ;;
+esac
+
+case "$cmd" in
+  up|down|stop|status) run_cli loop "$cmd" --root "$ROOT" "$@" ;;
+  check|env) run_cli loop env --root "$ROOT" "$@" ;;
+  logs)
+    log="$ROOT/.agents/data/loop/daemon.log"
+    if [ ! -f "$log" ]; then echo "No daemon log yet: $log"; exit 0; fi
+    exec tail -n 200 -f "$log"
+    ;;
+  help|-h|--help) usage ;;
+  *) echo "loop.sh: unknown command: $cmd" >&2; usage >&2; exit 2 ;;
+esac

package/dist/assets/.agents/aidlc/scripts/remote-state.mjs

@@ -5,7 +5,9 @@ import { readFile } from "node:fs/promises";
 import { promisify } from "node:util";
 import { createRemoteReviewerClient, createRemoteStateClient, featureConfig, remoteConfig, reviewerConfig } from "./lib/remote-state-client.mjs";
 import { compileContext } from "./lib/context-runtime.mjs";
-import { checkGate, closeTask, handoffTask, nextAction, readyTaskItems, recordLesson, recordNoLessons, reopenTask, transitionTask, validateState } from "./lib/store.mjs";
+import { explainFleetConflict } from "./lib/loop-holder.mjs";
+import { checkGate, closeTask, handoffTask, nextAction, readyTaskItems, recordLesson, recordNoLessons, recordTaskCommit, reopenTask, transitionTask, validateState } from "./lib/store.mjs";
+import { headCommit } from "./lib/repo-head.mjs";
 
 const parse = (argv) => {
   const positionals = []; const options = new Map();
@@ -54,9 +56,9 @@ export const runRemoteState = async (argv, client, root, git = {}) => {
   required(id, "task id");
   const allowed = {
     "task show": [], "task next": [], "task ready": [], "gate check": ["--gate"], "phase context": ["--phase", "--mode", "--item"],
-    "task create": ["--title", "--type", "--language", "--risk", "--area", "--feature"],
+    "task create": ["--title", "--type", "--language", "--risk", "--area", "--feature", "--base-commit"],
     "task status": ["--status", "--mode", "--reason", "--source"], "task item": ["--status", "--label", "--depends-on", "--owns"],
-    "task transition": ["--to", "--mode", "--reason", "--source"],
+    "task transition": ["--to", "--mode", "--reason", "--source", "--final-commit"],
     "task handoff": ["--kind", "--reason", "--source"], "task close": ["--reason", "--source"], "task reopen": ["--to", "--reason", "--source"],
     "decision set": ["--status", "--label", "--resolution"],
     "evidence add": ["--kind", "--result", "--gate", "--area", "--source", "--detail"],
@@ -118,6 +120,8 @@ export const runRemoteState = async (argv, client, root, git = {}) => {
       areas: (option("--area") ?? "root").split(",").map((item) => item.trim()).filter(Boolean), branch: "—",
       artifacts: { intent: `.agents/data/tasks/${id}/intent.md`, design: `.agents/data/tasks/${id}/design.md`, workplan: `.agents/data/tasks/${id}/workplan.md` },
       decisions: [], tasks: [], evidence: [], createdAt: recordedAt, updatedAt: recordedAt };
+    const baseCommit = option("--base-commit") ?? headCommit(root);
+    if (baseCommit !== undefined) recordTaskCommit(task, "baseCommit", baseCommit);
   } else {
     if (!previous) throw new Error(`Unknown task: ${id}`);
     task = structuredClone(previous);
@@ -161,6 +165,7 @@ export const runRemoteState = async (argv, client, root, git = {}) => {
       if (option("--mode") !== "audited") throw new Error("Transition requires --mode audited");
       const reason = required(option("--reason"), "--reason"); const source = required(option("--source"), "--source");
       const target = required(option("--to"), "--to");
+      if (target !== "done" && option("--final-commit") !== undefined) throw new Error("--final-commit is only accepted with --to done");
       if (target === "done" && task.featureId) {
         const manifest = await client.featureGet(task.featureId);
         const member = manifest?.feature?.tasks?.find((entry) => entry.id === id);
@@ -171,6 +176,7 @@ export const runRemoteState = async (argv, client, root, git = {}) => {
       const clone = structuredClone(state); clone.tasks[id] = task;
       transitionTask(clone, id, target);
       task = clone.tasks[id];
+      if (target === "done") { const finalCommit = option("--final-commit") ?? headCommit(root); if (finalCommit !== undefined) recordTaskCommit(task, "finalCommit", finalCommit); }
       task.evidence.push({ kind: "diagnostic", result: "pass", source, detail: `Audited transition ${previous.phase} → ${target}: ${reason}`, recordedAt: now() });
     } else if (route === "decision set") {
       const status = required(option("--status"), "--status");
@@ -307,5 +313,5 @@ if (isEntry) {
     const result = isReview ? await runRemoteReview(argv, createRemoteReviewerClient(config), config) : argv[0] === "feature" ? await runRemoteFeature(argv, createRemoteStateClient(config)) : argv[0] === "run" ? await runRemoteLease(argv, createRemoteStateClient(config)) : await runRemoteState(argv, createRemoteStateClient(config), config.projectRoot, config);
     console.log(JSON.stringify(result, null, 2));
     if (!result.ok) process.exitCode = 1;
-  } catch (error) { console.error(JSON.stringify({ ok: false, error: error.message, code: error.code, currentRevision: error.current?.revision }, null, 2)); process.exitCode = 1; }
+  } catch (error) { console.error(JSON.stringify({ ok: false, error: error.code === "FLEET_CONFLICT" ? explainFleetConflict(error.message) : error.message, code: error.code, currentRevision: error.current?.revision }, null, 2)); process.exitCode = 1; }
 }

package/dist/assets/.agents/aidlc/scripts/state.mjs

@@ -6,13 +6,14 @@
 import { acquireStateLock, approveAndAdvance, checkGate, closeTask, failEntry, handoffTask, listTaskSummaries, loadMemoryRegistry, loadState, loadTask, migrateState, nextAction, option, parseArguments, promoteAgenticMemory, rebuildLessonIndex, recordLesson, recordNoLessons, renderViews, reopenTask, retireAgenticMemory, rootOption, saveState, searchLessons, supersedeTask, transitionTask, validateArguments } from "./lib/runtime.mjs";
 import { readLiveLease } from "./lib/loop-lease.mjs";
 import { listFeatures, loadFeature, readyFeatureTasks, saveFeature } from "./lib/feature-store.mjs";
-import { readyTaskItems } from "./lib/store.mjs";
+import { readyTaskItems, recordTaskCommit } from "./lib/store.mjs";
+import { headCommit } from "./lib/repo-head.mjs";
 import { requireLocalAuthority } from "./lib/authority.mjs";
 
 try {
 requireLocalAuthority();
 const raw = process.argv.slice(2);
-const valueOptions = ["--root", "--status", "--limit", "--cursor", "--query", "--title", "--type", "--language", "--risk", "--area", "--mode", "--reason", "--source", "--to", "--kind", "--successor", "--label", "--resolution", "--result", "--gate", "--detail", "--summary", "--prevention", "--example", "--promotion", "--guidance", "--phase", "--priority", "--source-task", "--source-lesson", "--approved-by", "--switch-from", "--feature", "--depends-on", "--branch", "--owns"];
+const valueOptions = ["--root", "--status", "--limit", "--cursor", "--query", "--title", "--type", "--language", "--risk", "--area", "--mode", "--reason", "--source", "--to", "--kind", "--successor", "--label", "--resolution", "--result", "--gate", "--detail", "--summary", "--prevention", "--example", "--promotion", "--guidance", "--phase", "--priority", "--source-task", "--source-lesson", "--approved-by", "--switch-from", "--feature", "--depends-on", "--branch", "--owns", "--base-commit", "--final-commit"];
 const parsed = parseArguments(raw, { valueOptions, booleanOptions: ["--include-archive"] });
 const args = parsed.positionals;
 const [group, action, rawId] = args;
@@ -24,9 +25,9 @@ const schemas = {
   "task find": { minPositionals: 2, valueOptions: ["--query", "--status", "--limit", "--cursor"], booleanOptions: ["--include-archive"], requiredOptions: ["--query"] },
   "task next": { minPositionals: 3 },
   "task ready": { minPositionals: 3 },
-  "task create": { minPositionals: 3, valueOptions: ["--title", "--type", "--language", "--risk", "--area", "--switch-from", "--feature", "--depends-on"], requiredOptions: ["--title"] },
-  "task transition": { minPositionals: 3, valueOptions: ["--mode", "--reason", "--source", "--to"], requiredOptions: ["--mode", "--reason", "--source", "--to"], usage: "task transition requires --mode audited, --reason, --source, and --to" },
-  "task archive": { minPositionals: 3, valueOptions: ["--reason", "--source"], requiredOptions: ["--reason", "--source"] },
+  "task create": { minPositionals: 3, valueOptions: ["--title", "--type", "--language", "--risk", "--area", "--switch-from", "--feature", "--depends-on", "--base-commit"], requiredOptions: ["--title"] },
+  "task transition": { minPositionals: 3, valueOptions: ["--mode", "--reason", "--source", "--to", "--final-commit"], requiredOptions: ["--mode", "--reason", "--source", "--to"], usage: "task transition requires --mode audited, --reason, --source, and --to" },
+  "task archive": { minPositionals: 3, valueOptions: ["--reason", "--source", "--final-commit"], requiredOptions: ["--reason", "--source"] },
   "task handoff": { minPositionals: 3, valueOptions: ["--kind", "--reason", "--source"], requiredOptions: ["--kind", "--reason", "--source"] },
   "task close": { minPositionals: 3, valueOptions: ["--reason", "--source"], requiredOptions: ["--reason", "--source"] },
   "task supersede": { minPositionals: 3, valueOptions: ["--successor", "--reason", "--source"], requiredOptions: ["--successor", "--reason", "--source"] },
@@ -75,6 +76,7 @@ const summaryOptions = (query) => ({
   cursor: numberOption("--cursor", 0)
 });
 const warnings = [];
+const recordFinalCommit = (task) => { const sha = option(parsed, "--final-commit") ?? headCommit(root); if (sha !== undefined) recordTaskCommit(task, "finalCommit", sha); };
 const derivedStep = (code, hint, step) => { try { step(); } catch (error) { warnings.push({ code, message: error instanceof Error ? error.message : String(error), hint }); } };
 const persist = (tasks, rebuildLessons = false) => {
   const archived = saveState(root, state);
@@ -158,6 +160,8 @@ if (group === "state" && action === "migrate") {
     artifacts: { intent: `.agents/data/tasks/${id}/intent.md`, design: `.agents/data/tasks/${id}/design.md`, workplan: `.agents/data/tasks/${id}/workplan.md` },
     decisions: [], tasks: [], evidence: [], createdAt: recordedAt, updatedAt: recordedAt
   };
+  const baseCommit = option(parsed, "--base-commit") ?? headCommit(root);
+  if (baseCommit !== undefined) recordTaskCommit(task, "baseCommit", baseCommit);
   const acknowledgedTasks = acknowledged.map((ack) => state.tasks[ack]);
   for (const prior of acknowledgedTasks) {
     prior.evidence.push({ kind: "diagnostic", result: "pass", source: `task create ${id}`, detail: `Switch acknowledged: created ${id} while ${prior.id} was actionable; ${prior.id} keeps its state — resume with task next ${prior.id}`, recordedAt });
@@ -172,13 +176,16 @@ if (group === "state" && action === "migrate") {
 } else if (group === "task" && action === "transition") {
   const mode = option(parsed, "--mode"); const reason = option(parsed, "--reason"); const source = option(parsed, "--source");
   if (mode !== "audited" || !reason?.trim() || !source?.trim()) throw new Error("task transition requires --mode audited, --reason, and --source");
-  const from = state.tasks[id]?.phase; const target = option(parsed, "--to"); if (target === "done") requireFeaturePrerequisites(state.tasks[id]); const task = transitionTask(state, id, target);
+  const from = state.tasks[id]?.phase; const target = option(parsed, "--to"); if (target === "done") requireFeaturePrerequisites(state.tasks[id]);
+  if (target !== "done" && option(parsed, "--final-commit") !== undefined) throw new Error("--final-commit is only accepted with --to done");
+  const task = transitionTask(state, id, target);
+  if (target === "done") recordFinalCommit(task);
   task.evidence.push({ kind: "diagnostic", result: "pass", source, detail: `Audited transition ${from} → ${target}: ${reason}`, recordedAt: now() });
   persist([task]); respond(task);
 } else if (group === "task" && action === "archive") {
   const reason = option(parsed, "--reason"); const source = option(parsed, "--source");
   if (!reason?.trim() || !source?.trim()) throw new Error("task archive requires --reason and --source");
-  requireFeaturePrerequisites(state.tasks[id]); const task = transitionTask(state, id, "done");
+  requireFeaturePrerequisites(state.tasks[id]); const task = transitionTask(state, id, "done"); recordFinalCommit(task);
   task.evidence.push({ kind: "diagnostic", result: "pass", source, detail: `Archive to done: ${reason}`, recordedAt: now() });
   persist([task], true); respond(task);
 } else if (group === "task" && action === "handoff") {
@@ -270,7 +277,8 @@ if (group === "state" && action === "migrate") {
 } else if (group === "gate" && action === "approve") {
   const gate = option(parsed, "--gate"); const source = option(parsed, "--source");
   if (!id || !gate || !source) throw new Error("gate approve requires active task id, --gate, and explicit --source");
-  if (readLiveLease(root, id)) throw new Error(`Gate approval is unavailable while loop runner owns ${id}; wait for the runner to stop at the human gate`);
+  const runner = readLiveLease(root, id);
+  if (runner) throw new Error(`Gate approval is unavailable while loop runner owns ${id}; wait for the runner to stop at the human gate (task lease held by pid ${runner.pid}${runner.host ? ` on ${runner.host}` : ""}${runner.activity ? `, activity ${runner.activity}` : ""}${runner.expiresAt ? `, expires ${runner.expiresAt}` : ""}; inspect: node .agents/aidlc/scripts/loop-entry.mjs leases ${id})`);
   const outcome = approveAndAdvance(root, state, id, gate, source); persist([outcome.task]); emit({ task: outcome.task, idempotent: outcome.idempotent }, outcome.task);
 } else {
   throw new Error(usage);

package/dist/assets/ui/changes.js

@@ -0,0 +1,83 @@
+/*
+ * Task changes page. The diff is server-rendered (and escaped); this script only
+ * filters the item sections in place when the selector changes (the form still
+ * works without it), scrolls smoothly to a file, and applies the diff display
+ * settings from aidlcSettings: `diffWrap` toggles `is-wrapped` on the diff
+ * containers; `diffIgnoreWs` reloads the page with `?ws=ignore`, which the server
+ * maps to `git diff -w`. Loaded after common.js.
+ */
+(() => {
+  const settings = window.aidlcSettings;
+  const select = document.querySelector("[data-changes-select]");
+  const submit = document.querySelector("[data-changes-submit]");
+  const showItem = (item) => {
+    document.querySelectorAll("[data-change-item]").forEach((section) => {
+      section.hidden = Boolean(item) && section.getAttribute("data-change-item") !== item;
+    });
+  };
+  /* The URL with `?ws=ignore` set or cleared (other params and the hash are kept). */
+  const wsUrl = (ignore) => {
+    const params = new URLSearchParams(location.search);
+    if (ignore) params.set("ws", "ignore"); else params.delete("ws");
+    const query = params.toString();
+    return location.pathname + (query ? "?" + query : "") + location.hash;
+  };
+  const wsInUrl = () => new URLSearchParams(location.search).get("ws") === "ignore";
+  const applyWrap = (wrap) => {
+    document.querySelectorAll(".ad-changes-diff").forEach((diff) => diff.classList.toggle("is-wrapped", Boolean(wrap)));
+  };
+
+  if (settings) {
+    const current = settings.get();
+    applyWrap(current.diffWrap);
+    // The whitespace mode is a server-side diff option: the saved setting wins over the URL.
+    if (current.diffIgnoreWs !== wsInUrl()) { location.replace(wsUrl(current.diffIgnoreWs)); return; }
+    const options = document.querySelector("[data-changes-options]");
+    const wrapToggle = document.querySelector("[data-changes-wrap]");
+    const wsToggle = document.querySelector("[data-changes-ws]");
+    if (options) options.hidden = false;
+    if (wrapToggle) {
+      wrapToggle.checked = current.diffWrap;
+      wrapToggle.addEventListener("change", () => settings.set({ diffWrap: wrapToggle.checked }));
+    }
+    if (wsToggle) {
+      wsToggle.checked = current.diffIgnoreWs;
+      wsToggle.addEventListener("change", () => settings.set({ diffIgnoreWs: wsToggle.checked }));
+    }
+    // Covers the toggles here, the Settings dialog, and another tab saving.
+    settings.onChange((next, changed) => {
+      if (changed.includes("diffWrap")) { applyWrap(next.diffWrap); if (wrapToggle) wrapToggle.checked = next.diffWrap; }
+      if (changed.includes("diffIgnoreWs")) {
+        if (wsToggle) wsToggle.checked = next.diffIgnoreWs;
+        if (next.diffIgnoreWs !== wsInUrl()) location.assign(wsUrl(next.diffIgnoreWs));
+      }
+    });
+  }
+
+  if (select) {
+    if (submit) submit.hidden = true;
+    select.addEventListener("change", () => {
+      const item = select.value;
+      const params = new URLSearchParams(location.search);
+      if (item) params.set("item", item); else params.delete("item");
+      const query = params.toString();
+      const url = location.pathname + (query ? "?" + query : "");
+      // An item whose patch was left out of the whole-task view is loaded from the server.
+      const section = item ? document.querySelector('[data-change-item="' + CSS.escape(item) + '"]') : null;
+      if (section && section.hasAttribute("data-patch-omitted")) { location.assign(url); return; }
+      showItem(item);
+      history.replaceState(history.state, "", url);
+    });
+  }
+  document.addEventListener("click", (event) => {
+    const link = event.target instanceof Element ? event.target.closest("a[data-changes-file]") : null;
+    if (!link) return;
+    const target = document.getElementById((link.getAttribute("href") || "").slice(1));
+    if (!target) return;
+    event.preventDefault();
+    target.scrollIntoView({ behavior: "smooth", block: "start" });
+    history.replaceState(history.state, "", location.pathname + location.search + "#" + target.id);
+    target.classList.add("is-target");
+    setTimeout(() => target.classList.remove("is-target"), 1500);
+  });
+})();