gcf-aif-ext 0.7.3 → 0.7.5

package/README.md

@@ -52,7 +52,7 @@ On Windows, run `extension add` and `extension update` from PowerShell or cmd, n
 
 ### 0.7.1
 
-- `gcf board --json`: a ready item's worktree with no run lock and no session mark is a run that stopped (a timeout, a stop, a crash), not a run: the item reads `running: false`, `resumable: true`, and keeps its moves; its next run resumes the worktree.
+- `gcf board --json`: a ready item's worktree with no run lock and no session mark is a run that stopped (a timeout, a stop, a crash), not a run: the item reads `running: false`, `resumable: true`, and keeps its moves; its next run resumes the worktree. An agent session the harness kept (`.gcf-session/runs/<id>.agent.json`) makes a ready item `resumable` too, in either run mode, and shows as `resume: {ended, resets?}` (null without one).
 
 ### 0.7.0
 

package/extension.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
   "name": "gcf-aif-ext",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "description": "Game Context Framework for AI Factory",
   "skills": [
     "skills/gcf-init",

package/lib/board.js

@@ -120,6 +120,25 @@ function logOf(projectDir, id) {
   return existsSync(path.join(projectDir, log)) ? log : null;
 }
 
+/**
+ * How the agent session of the item's last run ended, when the harness kept it for a rerun to
+ * resume (`<id>.agent.json`): `{ended, resets?}`, or null. A file that is not a record is none.
+ */
+async function resumeOf(projectDir, id) {
+  try {
+    const file = path.join(projectDir, '.gcf-session', 'runs', `${id}.agent.json`);
+    const rec = JSON.parse(await readFile(file, 'utf8'));
+    if (typeof rec?.session_id !== 'string') return null;
+
+    return {
+      ended: String(rec.ended ?? ''),
+      ...(rec.resets ? { resets: String(rec.resets) } : {}),
+    };
+  } catch {
+    return null;
+  }
+}
+
 // Fields of the item file a board shows as they are: null or [] when the file has none.
 const SCALARS = [
   'title',
@@ -163,10 +182,15 @@ async function itemOf(projectDir, c, verified) {
   const ready = c.data.status === 'ready' && verified.has(id);
   // `running` and `verify` are not stored (§4): a live harness run lock or a fresh session mark
   // is a run; a trailer is a passed DoD. A worktree with neither is a run that stopped (a
-  // timeout, a stop, a crash): the item is ready, and its next run resumes that worktree.
+  // timeout, a stop, a crash): the item is ready, and its next run resumes that worktree. A
+  // session the harness kept (`resume`) is resumed by the next run in either mode.
   const running = runHolder(projectDir, id) !== null || sessionActive(projectDir, id);
+  const resume = c.data.status === 'ready' ? await resumeOf(projectDir, id) : null;
   const resumable =
-    !running && c.data.status === 'ready' && !ready && existsSync(worktreeOf(projectDir, id));
+    !running &&
+    c.data.status === 'ready' &&
+    !ready &&
+    (resume !== null || existsSync(worktreeOf(projectDir, id)));
 
   return {
     id,
@@ -179,6 +203,7 @@ async function itemOf(projectDir, c, verified) {
     ...(c.data.blocked ? { blocked: c.data.blocked } : {}),
     running,
     resumable,
+    resume,
     verified: ready,
     // What a board may offer (§4.1): nothing while a run drives the item.
     moves: running ? [] : movesOf(c.data),

package/lib/bundle.js

@@ -180,13 +180,21 @@ function plan(bundle, cur, ledger) {
   const writes = [];
   const note = `lines outside any part: ${bundle.stray.join(', ')} (a lost gcf:part marker?)`;
   const report = bundle.stray.length ? [{ part: 'bundle', outcome: 'invalid', note }] : [];
+  const keyOf = (p) => `${p.kind}:${p.name}`;
+  const keys = bundle.parts.map(keyOf);
   for (const p of bundle.parts) {
-    const key = `${p.kind}:${p.name}`;
+    const key = keyOf(p);
     if (!validName(p)) {
       report.push({ part: key, outcome: 'invalid', note: 'not a gcf doc, system or unit name' });
       continue;
     }
 
+    // Which copy is the designer's edit is not ours to guess: the later one would win silently.
+    if (keys.indexOf(key) !== keys.lastIndexOf(key)) {
+      report.push({ part: key, outcome: 'invalid', note: 'the bundle holds this part twice' });
+      continue;
+    }
+
     const v = verdict(p, cur.get(key) ?? null);
     if (p.kind === 'unit' && v === 'new' && ledger.known(p.name)) {
       report.push({ part: key, outcome: 'taken', note: 'the id is used: pick another slug' });

package/lib/ledger.js

@@ -71,9 +71,11 @@ export async function buildLedger(projectDir) {
   for (const d of design) for (const u of d.units) add(u.id, { state: 'design', file: d.file });
   for (const c of items) add(String(c.data.id), { state: 'item', file: `work/${c.name}` });
 
-  /** @type {Map<string, Set<string>>} */
+  // A list, not a set: two equal lines are two ends too (M12), a merge of branches that each
+  // ended the id the same way.
+  /** @type {Map<string, string[]>} */
   const terminal = new Map();
-  const mark = (id, event) => terminal.set(id, (terminal.get(id) ?? new Set()).add(event));
+  const mark = (id, event) => terminal.set(id, [...(terminal.get(id) ?? []), event]);
   for (const [id, event] of await recordLines(root, 'history.md'))
     if (HISTORY_EVENTS.includes(event)) mark(id, event);
   for (const [id] of await recordLines(root, 'graveyard.md')) mark(id, 'killed');

package/lib/session-mark.js

@@ -40,6 +40,14 @@ export function releaseSession(projectDir, id) {
   rmSync(markOf(projectDir, id), { force: true });
 }
 
+/**
+ * Forget the agent session the harness kept for a rerun of `id` (`<id>.agent.json`): a move,
+ * by hand or by an agent, ends the work it would resume.
+ */
+export function dropAgentSession(projectDir, id) {
+  rmSync(path.join(path.dirname(markOf(projectDir, id)), `${id}.agent.json`), { force: true });
+}
+
 /** Whether a session works the item now: a mark refreshed within SESSION_TTL_MS. */
 export function sessionActive(projectDir, id) {
   const file = markOf(projectDir, id);

package/lib/work-ops.js

@@ -11,7 +11,7 @@ import path from 'node:path';
 import { parse, serialize } from './frontmatter.js';
 import { buildLedger } from './ledger.js';
 import { readConfig } from './gcf-paths.js';
-import { atomicWrite } from './safe-path.js';
+import { atomicWrite, resolveInside } from './safe-path.js';
 import { allowedFrom, decisionFits, FEATURE_ONLY, fromOf } from './transitions.js';
 import { ITEM_TYPES, DEFAULT_GATE, GATES, SEVERITIES, UNIT_ITEM_TYPES } from './validate-item.js';
 import { isValidId } from './id.js';
@@ -37,8 +37,8 @@ import {
 } from './live.js';
 import { dropInbox } from './inbox.js';
 import { refuseByPhase } from './phase.js';
-import { runHolder } from './main-lock.js';
-import { releaseSession, sessionActive } from './session-mark.js';
+import { runHolder, withMainLock } from './main-lock.js';
+import { dropAgentSession, releaseSession, sessionActive } from './session-mark.js';
 
 /**
  * Options of a committed move; each move reads the ones it needs.
@@ -160,14 +160,13 @@ function unfinishedChildren(ledger, feature) {
 }
 
 /**
- * Open a move on item `id` from the statuses `move` allows: the files it touches, its steps,
- * and the LIVE.md edits folded into a single write at the end.
+ * Refuse a move on item `id` while a harness run or another agent session works it. `self` is
+ * the item this session drives itself (null: none).
+ * @param {string} projectDir
+ * @param {string} id
+ * @param {string | null} [self]
  */
-async function begin(projectDir, id, move) {
-  const root = gcfOf(projectDir);
-  const ledger = await buildLedger(projectDir);
-  const item = itemOf(ledger, id);
-  need(move, item);
+function refuseRunning(projectDir, id, self = process.env.GCF_RUN_ITEM ?? null) {
   const run = runHolder(projectDir, id);
   if (run)
     throw new Error(
@@ -176,11 +175,23 @@ async function begin(projectDir, id, move) {
     );
   // The session that claimed the item moves it itself (GCF_RUN_ITEM, set by `--claimed` or by
   // a harness run on main); anyone else waits, as for a run lock.
-  if (sessionActive(projectDir, id) && process.env.GCF_RUN_ITEM !== id)
+  if (sessionActive(projectDir, id) && self !== id)
     throw new Error(
       `${id} is worked by an agent session (gcf claim): wait until it moves the item, or run ` +
         `ai-factory gcf release ${id} when no session works it`,
     );
+}
+
+/**
+ * Open a move on item `id` from the statuses `move` allows: the files it touches, its steps,
+ * and the LIVE.md edits folded into a single write at the end.
+ */
+async function begin(projectDir, id, move) {
+  const root = gcfOf(projectDir);
+  const ledger = await buildLedger(projectDir);
+  const item = itemOf(ledger, id);
+  need(move, item);
+  refuseRunning(projectDir, id);
   const files = [item.file];
   const steps = [];
   const liveOps = [];
@@ -217,8 +228,10 @@ async function finish(m, move, tail, commit) {
     commit,
     inputs: [m.item.file],
   });
-  // A move on the item ends the session that worked it: the board stops showing it running.
+  // A move on the item ends the session that worked it: the board stops showing it running,
+  // and no rerun resumes it.
   releaseSession(m.projectDir, String(m.item.data.id));
+  dropAgentSession(m.projectDir, String(m.item.data.id));
 
   return hash;
 }
@@ -229,6 +242,16 @@ const writeItem = (item, data, body = item.body) => atomicWrite(item.file, seria
 const without = (data, ...keys) =>
   Object.fromEntries(Object.entries(data).filter(([k]) => !keys.includes(k)));
 
+/** Refuse a move on an unplayed item edited since its close; `then` is where the edit goes. */
+function refuseEdited(item, then) {
+  if (matchesFrozen(item)) return;
+  throw new Error(
+    `${item.data.id}: an unplayed item's body and live: are frozen, and this one was edited — ` +
+      `save the edit aside, restore the file (git restore gcf/work/${item.data.id}.md ` +
+      `discards it), make the move, then ${then}`,
+  );
+}
+
 /**
  * The item's lines leave its systems docs and its added capability leaves LIVE.md. A line
  * another unplayed item also wrote stays: that item's body still owes it to systems/.
@@ -236,12 +259,7 @@ const without = (data, ...keys) =>
 function unplay(m, item) {
   // The gate checks `frozen` only on a file that stays unplayed: a tune or a kill of an edited
   // item would take the edited lines out and leave the frozen ones in systems/ for good.
-  if (!matchesFrozen(item))
-    throw new Error(
-      `${item.data.id}: an unplayed item's body and live: are frozen, and this one was edited — ` +
-        `save the edit aside, restore the file (git restore gcf/work/${item.data.id}.md ` +
-        'discards it), make the move, then apply the edit to the ready item',
-    );
+  refuseEdited(item, 'apply the edit to the ready item');
   const systems = item.data.system ?? [];
   m.leaving.add(String(item.data.id));
   m.touch(...systemFiles(m.root, systems));
@@ -283,7 +301,8 @@ function tracked(projectDir, file) {
  */
 function archivePlan(m, item) {
   const rel = item.data.plan ?? `.ai-factory/plans/${item.data.id}.md`;
-  const src = path.resolve(m.projectDir, rel);
+  // The plan is moved and deleted: a `plan:` out of the project would take another tree's file.
+  const src = resolveInside(m.projectDir, rel);
   if (!existsSync(src) || !tracked(m.projectDir, src)) return null;
   const destRel = `.ai-factory/archive/plans/${path.basename(src)}`;
   const dest = path.resolve(m.projectDir, destRel);
@@ -456,7 +475,7 @@ function refuseOpenDepends(m, move, opts = {}) {
 /** ready → awaiting-verdict / awaiting-decision; `since` marks where the wait began.
  * @param {MoveOpts} [opts]
  */
-export async function submitItem(projectDir, id, opts = {}) {
+async function submitItemUnlocked(projectDir, id, opts = {}) {
   const { commit = true } = opts;
   const m = await begin(projectDir, id, 'submit');
   if (m.item.data.gate === 'auto')
@@ -528,7 +547,7 @@ function closeFeature(m) {
  * unit collapses into its systems docs and stays as unplayed; anything else ends in history.
  * @param {MoveOpts} [opts]
  */
-export async function closeItem(projectDir, id, opts = {}) {
+async function closeItemUnlocked(projectDir, id, opts = {}) {
   const { constraints = [], commit = true } = opts;
   const m = await begin(projectDir, id, 'close');
   const unplayed = SOFT.includes(m.item.data.type);
@@ -554,6 +573,8 @@ async function keep(m, constraints) {
   const { item } = m;
   refuseOpenDepends(m, 'verdict keep');
   if (item.data.status === 'unplayed') {
+    // systems/ and LIVE.md hold the frozen body: an edit made since would leave with the file.
+    refuseEdited(item, `carry the edit in a new item with reopens: ${item.data.id}`);
     endToHistory(m, item, 'collapsed', { applyLive: false });
 
     return;
@@ -599,7 +620,7 @@ async function tune(m, note) {
 /** keep | tune | kill on an item waiting for its verdict or unplayed (Methodology §5.4).
  * @param {MoveOpts} [opts]
  */
-export async function verdictItem(projectDir, id, verdict, opts = {}) {
+async function verdictItemUnlocked(projectDir, id, verdict, opts = {}) {
   const { note = '', tags = [], remove, constraints = [], commit = true } = opts;
   if (!['keep', 'tune', 'kill'].includes(verdict)) throw new Error(`Unknown verdict: ${verdict}`);
   const m = await begin(projectDir, id, `verdict:${verdict}`);
@@ -617,9 +638,11 @@ export async function verdictItem(projectDir, id, verdict, opts = {}) {
 function killFeature(m, { reason, remove }) {
   const { item, ledger } = m;
   const shipped = featureShipped(ledger, item);
-  for (const c of item.data.children ?? []) {
-    const child = ledger.item(c);
-    if (!child) continue;
+  const children = (item.data.children ?? []).map((c) => ledger.item(c)).filter(Boolean);
+  // A child's file goes with the feature: an agent working it would lose it mid-run.
+  // No session kills its own item through its feature: the claimed child counts as running too.
+  for (const child of children) refuseRunning(m.projectDir, String(child.data.id), null);
+  for (const child of children) {
     endToGraveyard(m, child, {
       reason: `feature ${item.data.id} killed: ${reason}`,
       removal: false,
@@ -674,7 +697,7 @@ function fitDecision(choice, item) {
 /** The operator's decisions (Methodology §4.1): spikes, decision items, bugs and features.
  * @param {MoveOpts} [opts]
  */
-export async function decideItem(projectDir, id, choice, opts = {}) {
+async function decideItemUnlocked(projectDir, id, choice, opts = {}) {
   const { reason = '', remove, commit = true } = opts;
   if (!DECIDE[choice])
     throw new Error(`Unknown decision: ${choice} (${Object.keys(DECIDE).join(' | ')})`);
@@ -689,7 +712,7 @@ export async function decideItem(projectDir, id, choice, opts = {}) {
 /** ready → blocked, with the reason or the question for the operator.
  * @param {MoveOpts} [opts]
  */
-export async function blockItem(projectDir, id, opts = {}) {
+async function blockItemUnlocked(projectDir, id, opts = {}) {
   const { reason, commit = true } = opts;
   const why = String(reason ?? '').trim();
   if (!why) throw new Error('a block needs a reason or a question');
@@ -703,7 +726,7 @@ export async function blockItem(projectDir, id, opts = {}) {
 /** blocked | parked → ready; a note (an answer, a delivered asset file) goes to `notes:`.
  * @param {MoveOpts} [opts]
  */
-export async function unblockItem(projectDir, id, opts = {}) {
+async function unblockItemUnlocked(projectDir, id, opts = {}) {
   const { note = '', commit = true } = opts;
   const m = await begin(projectDir, id, 'unblock');
   if (m.item.data.status === 'parked') dropKnownIssue(m, id);
@@ -725,7 +748,7 @@ export async function unblockItem(projectDir, id, opts = {}) {
 /** Any stored status → graveyard; an unplayed item leaves as a kill does.
  * @param {MoveOpts} [opts]
  */
-export async function dropItem(projectDir, id, opts = {}) {
+async function dropItemUnlocked(projectDir, id, opts = {}) {
   const { reason, tags = [], remove, commit = true } = opts;
   const m = await begin(projectDir, id, 'drop');
   if (m.item.data.type === 'feature' && (m.item.data.children ?? []).some((c) => m.ledger.item(c)))
@@ -855,7 +878,7 @@ function newItemText(spec, gate, since) {
  * Rank items in the given order: `priority` 1, 2, 3… (lower runs sooner). One commit
  * `gcf(priority)`. A board sends a column's new order after a drag; the console names the ids.
  */
-export async function prioritizeItems(projectDir, ids, { commit = true } = {}) {
+async function prioritizeItemsUnlocked(projectDir, ids, { commit = true } = {}) {
   if (!ids.length) throw new Error('name the items in the order they should run');
   if (new Set(ids).size !== ids.length) throw new Error('an id is named twice');
   const ledger = await buildLedger(projectDir);
@@ -896,7 +919,7 @@ export async function prioritizeItems(projectDir, ids, { commit = true } = {}) {
  * A new work item in ready (or blocked), no commit. A design unit enters work through `take`,
  * not here: its body is the unit's slots. `from` erases the inbox entry it came from.
  */
-export async function newItem(projectDir, spec) {
+async function newItemUnlocked(projectDir, spec) {
   const root = gcfOf(projectDir);
   const ledger = await buildLedger(projectDir);
   const gate = checkNew(ledger, spec);
@@ -930,3 +953,41 @@ export async function newItem(projectDir, spec) {
 
   return { item: `gcf/work/${spec.id}.md`, hash };
 }
+
+/**
+ * A committed move holds the main lock from its first read to its commit (Methodology §7): one
+ * that read the ledger before taking it would write over a move committed meanwhile.
+ * @template T
+ * @param {string} projectDir
+ * @param {boolean} commit
+ * @param {() => Promise<T>} move
+ */
+const locked = (projectDir, commit, move) => (commit ? withMainLock(projectDir, move) : move());
+
+/** @type {typeof submitItemUnlocked} */
+export const submitItem = (projectDir, id, opts = {}) =>
+  locked(projectDir, opts.commit ?? true, () => submitItemUnlocked(projectDir, id, opts));
+/** @type {typeof closeItemUnlocked} */
+export const closeItem = (projectDir, id, opts = {}) =>
+  locked(projectDir, opts.commit ?? true, () => closeItemUnlocked(projectDir, id, opts));
+/** @type {typeof verdictItemUnlocked} */
+export const verdictItem = (projectDir, id, verdict, opts = {}) =>
+  locked(projectDir, opts.commit ?? true, () => verdictItemUnlocked(projectDir, id, verdict, opts));
+/** @type {typeof decideItemUnlocked} */
+export const decideItem = (projectDir, id, choice, opts = {}) =>
+  locked(projectDir, opts.commit ?? true, () => decideItemUnlocked(projectDir, id, choice, opts));
+/** @type {typeof blockItemUnlocked} */
+export const blockItem = (projectDir, id, opts = {}) =>
+  locked(projectDir, opts.commit ?? true, () => blockItemUnlocked(projectDir, id, opts));
+/** @type {typeof unblockItemUnlocked} */
+export const unblockItem = (projectDir, id, opts = {}) =>
+  locked(projectDir, opts.commit ?? true, () => unblockItemUnlocked(projectDir, id, opts));
+/** @type {typeof dropItemUnlocked} */
+export const dropItem = (projectDir, id, opts = {}) =>
+  locked(projectDir, opts.commit ?? true, () => dropItemUnlocked(projectDir, id, opts));
+/** @type {typeof prioritizeItemsUnlocked} */
+export const prioritizeItems = (projectDir, ids, opts = {}) =>
+  locked(projectDir, opts.commit ?? true, () => prioritizeItemsUnlocked(projectDir, ids, opts));
+/** @type {typeof newItemUnlocked} */
+export const newItem = (projectDir, spec) =>
+  locked(projectDir, spec.commit ?? false, () => newItemUnlocked(projectDir, spec));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcf-aif-ext",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "description": "Game Context Framework for AI Factory",
   "type": "module",
   "license": "MIT",