@syntax-syllogism/aloop 0.5.3 → 0.6.1

package/src/state.mjs

@@ -1,5 +1,129 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { access, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { readdirSync, renameSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
+import { MANIFEST_VERSION, Manifest } from './manifest.mjs';
+
+export const STATE_SCHEMA_VERSION = 1;
+
+function newRunId() {
+  return `${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`;
+}
+
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === 'EPERM';
+  }
+}
+
+function isProcessGroupAlive(groupId) {
+  if (process.platform === 'win32' || !Number.isInteger(groupId) || groupId <= 0 || groupId === process.pid) return false;
+  try {
+    process.kill(-groupId, 0);
+    return true;
+  } catch (error) {
+    return error.code === 'EPERM';
+  }
+}
+
+function isActiveProcessAlive(activeProcess) {
+  return isProcessGroupAlive(activeProcess?.processGroupId) || isProcessAlive(activeProcess?.pid);
+}
+
+async function readActiveProcess(dir) {
+  try {
+    return JSON.parse(await readFile(join(dir, 'active-command.json'), 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT' || error instanceof SyntaxError) return null;
+    throw error;
+  }
+}
+
+function lockOwnerName(lockToken) {
+  return `owner-${lockToken.pid}-${lockToken.token}`;
+}
+
+function lockOwnerPath(lockPath, lockToken) {
+  return join(lockPath, lockOwnerName(lockToken));
+}
+
+function parseLockOwner(name) {
+  const match = /^owner-(\d+)-([0-9a-f-]+)$/.exec(name);
+  if (!match) return null;
+  return { pid: Number(match[1]), token: match[2] };
+}
+
+function unreadableLockError(path) {
+  return new Error(`Run already active; lock directory "${path}" is unreadable or stale.`);
+}
+
+async function readLockOwner(lockPath) {
+  let entries;
+  try {
+    entries = await readdir(lockPath);
+  } catch (error) {
+    if (error.code === 'ENOENT') throw error;
+    throw unreadableLockError(lockPath);
+  }
+
+  const owners = entries.filter((entry) => parseLockOwner(entry));
+  const temporaryEntries = entries.filter((entry) => entry.endsWith('.tmp'));
+  if (entries.length === 0) return null;
+  if (owners.length !== 1 || owners.length + temporaryEntries.length !== entries.length) {
+    throw unreadableLockError(lockPath);
+  }
+
+  const owner = parseLockOwner(owners[0]);
+  try {
+    JSON.parse(await readFile(join(lockPath, owners[0]), 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') throw error;
+    throw unreadableLockError(lockPath);
+  }
+  return { ...owner, path: join(lockPath, owners[0]) };
+}
+
+function validateSchema(data, source) {
+  const version = Object.hasOwn(data, 'schemaVersion') ? data.schemaVersion : 0;
+  if (!Number.isInteger(version)) {
+    throw new Error(
+      `Unsupported ${source} schemaVersion ${version}; expected an integer version.`,
+    );
+  }
+  if (version > STATE_SCHEMA_VERSION) {
+    throw new Error(
+      `Unsupported ${source} schemaVersion ${version}; this aloop version supports ${STATE_SCHEMA_VERSION}.`,
+    );
+  }
+  if (version < STATE_SCHEMA_VERSION && version !== 0) {
+    throw new Error(
+      `Unsupported ${source} schemaVersion ${version}; no migration is available to ${STATE_SCHEMA_VERSION}.`,
+    );
+  }
+  return version === 0 ? { ...data, schemaVersion: STATE_SCHEMA_VERSION } : data;
+}
+
+async function atomicWrite(path, contents) {
+  const tempPath = `${path}.tmp`;
+  await writeFile(tempPath, contents, 'utf8');
+  await rename(tempPath, path);
+}
+
+async function publishLock(lockPath, lockToken, contents) {
+  const temporaryPath = `${lockPath}.tmp-${lockToken.token}`;
+  try {
+    await mkdir(temporaryPath);
+    await writeFile(lockOwnerPath(temporaryPath, lockToken), contents, { encoding: 'utf8', flag: 'wx' });
+    await rename(temporaryPath, lockPath);
+  } catch (error) {
+    await rm(temporaryPath, { recursive: true, force: true }).catch(() => {});
+    throw error;
+  }
+}
 
 /**
  * Run state, persisted after every phase.
@@ -21,36 +145,207 @@ export function slugFor(input) {
 }
 
 export class RunState {
-  constructor(dir, data, readOnly = false) {
+  constructor(dir, data, readOnly = false, manifest = new Manifest(), lockToken = null, manifestMetadata = {}) {
     this.dir = dir;
     this.data = data;
     this.readOnly = readOnly;
+    this.manifest = manifest;
+    this.manifestMetadata = manifestMetadata;
+    this.lockToken = lockToken;
+    this.exitHandler = null;
   }
 
-  static async open(runsDir, slug, seed, { readOnly = false } = {}) {
+  static async open(
+    runsDir,
+    slug,
+    seed,
+    { readOnly = false, create = !readOnly, resume = false, lock = !readOnly } = {},
+  ) {
     const dir = join(runsDir, slug);
-    await mkdir(dir, { recursive: true });
-    const path = join(dir, 'state.json');
-    let data;
+    const freshData = {
+      runId: seed.runId ?? newRunId(),
+      startedAt: new Date().toISOString(),
+      completed: [],
+      rounds: {},
+      reviewedShas: {},
+      ...seed,
+      schemaVersion: STATE_SCHEMA_VERSION,
+    };
+    let lockToken = null;
     try {
-      data = JSON.parse(await readFile(path, 'utf8'));
+      if (create) await mkdir(dir, { recursive: true });
+      if (lock && create) lockToken = await RunState.acquireLock(dir, freshData.runId);
+
+      let data = freshData;
+      if (create) {
+        const path = join(dir, 'state.json');
+        let hasExistingRun = false;
+        try {
+          const persisted = validateSchema(JSON.parse(await readFile(path, 'utf8')), 'state');
+          data = {
+            ...persisted,
+            runId: persisted.runId ?? freshData.runId,
+            schemaVersion: STATE_SCHEMA_VERSION,
+          };
+          hasExistingRun = true;
+        } catch (error) {
+          if (error.code !== 'ENOENT') throw error;
+        }
+
+        const manifestPath = join(dir, 'manifest.json');
+        try {
+          validateSchema(JSON.parse(await readFile(manifestPath, 'utf8')), 'manifest');
+          hasExistingRun = true;
+        } catch (error) {
+          if (error.code !== 'ENOENT') throw error;
+        }
+        if (hasExistingRun && !resume) {
+          throw new Error(
+            `Run directory "${dir}" already contains a run; use --resume to continue it or choose a new --name.`,
+          );
+        }
+      }
+      let manifest = new Manifest();
+      let manifestMetadata = {};
+      if (create) {
+        try {
+          const saved = JSON.parse(await readFile(join(dir, 'manifest.json'), 'utf8'));
+          manifest = new Manifest(saved.phases ?? []);
+          manifestMetadata = saved;
+        } catch (error) {
+          if (error.code !== 'ENOENT') throw error;
+        }
+      }
+      const state = new RunState(dir, data, readOnly, manifest, lockToken, manifestMetadata);
+      if (lockToken) state.installExitHandler();
+      return state;
+    } catch (error) {
+      if (lockToken) await RunState.releaseLock(dir, lockToken);
+      throw error;
+    }
+  }
+
+  static async acquireLock(dir, runId) {
+    const path = join(dir, 'lock');
+    const lockToken = { pid: process.pid, startedAt: new Date().toISOString(), runId, token: randomUUID() };
+    const contents = `${JSON.stringify(lockToken, null, 2)}\n`;
+    while (true) {
+      try {
+        await publishLock(path, lockToken, contents);
+        return lockToken;
+      } catch (error) {
+        if (!['EEXIST', 'ENOTEMPTY'].includes(error.code)) throw error;
+      }
+
+      let existing;
+      try {
+        existing = await readLockOwner(path);
+      } catch (readError) {
+        if (readError.code === 'ENOENT') continue;
+        throw readError;
+      }
+      if (!existing) {
+        const abandonedPath = `${path}.abandoned-${lockToken.token}`;
+        try {
+          await rename(path, abandonedPath);
+        } catch (renameError) {
+          if (renameError.code === 'ENOENT') continue;
+          throw renameError;
+        }
+        await rm(abandonedPath, { recursive: true, force: true });
+        continue;
+      }
+      if (isProcessAlive(existing.pid)) {
+        throw new Error(
+          `Run already active for "${dir}" (pid ${existing.pid}); wait for it to finish or remove a stale lock after confirming the process is gone.`,
+        );
+      }
+
+      const activeProcess = await readActiveProcess(dir);
+      if (isActiveProcessAlive(activeProcess)) {
+        throw new Error(
+          `Run still has an active command for "${dir}" (pid ${activeProcess.pid}); wait for it to finish before resuming.`,
+        );
+      }
+
+      try {
+        await rename(existing.path, lockOwnerPath(path, lockToken));
+      } catch (renameError) {
+        if (renameError.code === 'ENOENT') continue;
+        throw renameError;
+      }
+      try {
+        await atomicWrite(lockOwnerPath(path, lockToken), contents);
+        return lockToken;
+      } catch (writeError) {
+        await RunState.releaseLock(dir, lockToken);
+        throw writeError;
+      }
+    }
+  }
+
+  static async releaseLock(dir, lockToken) {
+    const path = join(dir, 'lock');
+    const ownerPath = lockOwnerPath(path, lockToken);
+    const releasedPath = `${path}.released-${lockToken.token}`;
+    try {
+      const current = await readLockOwner(path);
+      if (!current || current.path !== ownerPath) return;
+      await rename(path, releasedPath);
     } catch (error) {
       if (error.code !== 'ENOENT') throw error;
-      data = {
-        startedAt: new Date().toISOString(),
-        completed: [],
-        rounds: {},
-        reviewedShas: {},
-        ...seed,
-      };
+      return;
     }
-    return new RunState(dir, data, readOnly);
+    await rm(releasedPath, { recursive: true, force: true });
+  }
+
+  installExitHandler() {
+    this.exitHandler = () => {
+      try {
+        if (!readdirSync(this.lockPath).includes(lockOwnerName(this.lockToken))) return;
+        const releasedPath = `${this.lockPath}.released-${this.lockToken.token}`;
+        renameSync(this.lockPath, releasedPath);
+        rmSync(releasedPath, { recursive: true, force: true });
+      } catch (error) {
+        if (error.code !== 'ENOENT') {
+          // The process is exiting; there is no useful recovery path here.
+        }
+      }
+    };
+    process.once('exit', this.exitHandler);
   }
 
   get path() {
     return join(this.dir, 'state.json');
   }
 
+  get lockPath() {
+    return join(this.dir, 'lock');
+  }
+
+  get manifestPath() {
+    return join(this.dir, 'manifest.json');
+  }
+
+  get snapshotPath() {
+    return join(this.dir, 'snapshot.json');
+  }
+
+  async hasSnapshot() {
+    try {
+      await access(this.snapshotPath);
+      return true;
+    } catch (error) {
+      if (error.code === 'ENOENT') return false;
+      throw error;
+    }
+  }
+
+  async saveSnapshot(snapshot) {
+    if (this.readOnly || await this.hasSnapshot()) return;
+    await atomicWrite(this.snapshotPath, `${JSON.stringify(snapshot, null, 2)}\n`);
+  }
+
   logPath(name) {
     return join(this.dir, `${name}.log`);
   }
@@ -74,6 +369,22 @@ export class RunState {
     await this.save();
   }
 
+  async saveManifest(manifest) {
+    if (this.readOnly) return;
+    this.manifestMetadata = { ...this.manifestMetadata, ...manifest };
+    await this.persistManifest();
+  }
+
+  async persistManifest() {
+    const data = {
+      ...this.manifestMetadata,
+      manifestVersion: MANIFEST_VERSION,
+      schemaVersion: STATE_SCHEMA_VERSION,
+      phases: this.manifest.entries,
+    };
+    await atomicWrite(this.manifestPath, `${JSON.stringify(data, null, 2)}\n`);
+  }
+
   /**
    * Persist, unless this is a dry run.
    *
@@ -82,7 +393,18 @@ export class RunState {
    */
   async save() {
     if (this.readOnly) return;
+    this.data.schemaVersion = STATE_SCHEMA_VERSION;
+    if (!this.data.runId) this.data.runId = newRunId();
     this.data.updatedAt = new Date().toISOString();
-    await writeFile(this.path, `${JSON.stringify(this.data, null, 2)}\n`);
+    await atomicWrite(this.path, `${JSON.stringify(this.data, null, 2)}\n`);
+    await this.persistManifest();
+  }
+
+  async release() {
+    if (!this.lockToken) return;
+    if (this.exitHandler) process.removeListener('exit', this.exitHandler);
+    const lockToken = this.lockToken;
+    this.lockToken = null;
+    await RunState.releaseLock(this.dir, lockToken);
   }
 }

package/src/verdict.mjs

@@ -19,6 +19,34 @@ function extractJson(text) {
   }
 }
 
+function validateFindings(list, label) {
+  list.forEach((finding, index) => {
+    const prefix = `${label}[${index}] is malformed:`;
+    if (!finding || typeof finding !== 'object' || Array.isArray(finding)) {
+      throw new Error(`${prefix} expected an object.`);
+    }
+
+    const description = finding.issue ?? finding.summary;
+    if (typeof description !== 'string' || !description.trim()) {
+      throw new Error(`${prefix} expected a non-empty issue or summary string.`);
+    }
+    if ('file' in finding && typeof finding.file !== 'string') {
+      throw new Error(`${prefix} file must be a string.`);
+    }
+    if ('line' in finding && typeof finding.line !== 'number') {
+      throw new Error(`${prefix} line must be a number.`);
+    }
+  });
+}
+
+function parseFindingList(value, label) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) {
+    throw new Error(`${label} must be an array.`);
+  }
+  return value;
+}
+
 /**
  * Validate a verdict.
  *
@@ -33,14 +61,20 @@ export function parseVerdict(text) {
   if (![APPROVED, CHANGES_REQUESTED].includes(verdict)) {
     throw new Error(`Verdict must be ${APPROVED} or ${CHANGES_REQUESTED}, got ${JSON.stringify(data.verdict)}.`);
   }
-  const blocking = Array.isArray(data.blocking) ? data.blocking : [];
+  const blocking = parseFindingList(data.blocking, 'blocking');
+  const nits = parseFindingList(data.nits, 'nits');
+  validateFindings(blocking, 'blocking');
+  validateFindings(nits, 'nits');
   if (verdict === CHANGES_REQUESTED && blocking.length === 0) {
     throw new Error(`Verdict is ${CHANGES_REQUESTED} but lists no blocking findings.`);
   }
+  if (verdict === APPROVED && blocking.length > 0) {
+    throw new Error(`Verdict is ${APPROVED} but lists ${blocking.length} blocking findings.`);
+  }
   return {
     verdict,
     blocking,
-    nits: Array.isArray(data.nits) ? data.nits : [],
+    nits,
     summary: typeof data.summary === 'string' ? data.summary : '',
   };
 }

package/src/worktree.mjs

@@ -0,0 +1,33 @@
+import { mkdir, stat } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+
+async function directoryExists(path) {
+  try { return (await stat(path)).isDirectory(); } catch { return false; }
+}
+
+export async function resumedWorktree(git, repoRoot, branch, savedPath) {
+  if (!savedPath) return null;
+  if (resolve(savedPath) === resolve(repoRoot)) {
+    if (await directoryExists(savedPath)) return savedPath;
+  } else {
+    const registeredPath = await git.worktreePath(branch);
+    if (registeredPath && await directoryExists(registeredPath)) return registeredPath;
+  }
+  throw new Error(`Saved worktree "${savedPath}" for branch "${branch}" is unavailable. Restore it or re-register it with git worktree before resuming.`);
+}
+
+export async function planWorktree(git, config, slug, branch, repoRoot) {
+  if (!config.worktrees) return { worktree: repoRoot, willCreate: false };
+  const root = config.worktreeRoot ? resolve(repoRoot, config.worktreeRoot) : join(dirname(repoRoot), '.loop-worktrees');
+  const existing = await git.worktreePath(branch);
+  if (existing) return { worktree: existing, willCreate: false };
+  return { worktree: join(root, slug), willCreate: true };
+}
+
+export async function setupWorktree(git, config, slug, branch, repoRoot, baseBranch) {
+  const plan = await planWorktree(git, config, slug, branch, repoRoot);
+  if (!plan.willCreate) return { worktree: plan.worktree, created: false, worktreeCreated: false };
+  await mkdir(dirname(plan.worktree), { recursive: true });
+  const result = await git.addWorktree(plan.worktree, branch, baseBranch);
+  return { worktree: plan.worktree, created: result.created, worktreeCreated: true };
+}

package/presets/work-item/prompts/git.md

@@ -1,44 +0,0 @@
-The code-producing phases have already committed their work in `{{REPO}}`, on
-branch `{{BRANCH}}`. Verify the worktree is clean and do not create any code
-commits in this phase.
-
-- Inspect the full worktree and recent branch history before pushing.
-- Do _NOT_ include notes about co-author / author.
-- Report the existing code commit hashes and messages, validation performed,
-  and whether the worktree is clean.
-- Push to `{{REMOTE}}` and create a PR to `{{BASE_BRANCH}}` on the same repo. PR
-  body should be < 250 words.
-
-The PR body should cover what changed and why, a summary of the task, the
-review outcome (how many rounds, plus any recorded disagreements from the task file's
-`## Code Review` section if present), and anything deliberately left out of scope.
-
-## The task file
-
-If a task file is present (`{{TASK_FILE}}`), update it without committing it:
-
-- Set the frontmatter `status` to `UNDER REVIEW`.
-- Append a `## Changelog` entry listing the code commits (short SHA + subject)
-  and the PR URL once you have it.
-- Use only `TODO`, `IN PROGRESS`, `UNDER REVIEW`, or `DONE` as statuses.
-
-A separate job or workflow commits task file changes if needed. Do not commit the
-task file or make any other commits in its repository.
-
-## Boundaries
-
-- If the worktree is **not** clean — `git status --porcelain` reports anything —
-  do **not** edit files, tests, or configuration to make it clean, and do not
-  create commits. A dirty tree at this phase is a pipeline error: stop
-  immediately and report the offending paths. Reconciling it is out of scope
-  here, and the earlier phase that left the work uncommitted must be resumed
-  instead.
-- **Do not merge the pull request**, and do not enable auto-merge. A human
-  decides; an open PR is the correct end state for this run.
-- Never force-push, and never rewrite commits that already exist on
-  `{{REMOTE}}`.
-- If the push is rejected because the branch moved, stop and report it rather
-  than forcing anything.
-
-The separate task-file workflow and cron process own updates to that repository;
-keep code and task-file commits separate.