gcf-aif-ext 0.10.0 → 0.10.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -50,6 +50,15 @@ Updating preserves `gcf/`, `cnlp.config.json` and the pre-commit hook. Run `ai-f
50
50
 
51
51
  On Windows, run `extension add` and `extension update` from PowerShell or cmd, not Git Bash: the installer unpacks with `tar`, and Git Bash's GNU tar reads `C:\…` as a remote host (`Cannot connect to C: resolve failed`). The Windows `tar.exe` handles it.
52
52
 
53
+ ### 0.10.2
54
+
55
+ - `gcf claim` is exclusive. The session mark names its owner: `GCF_RUN_OWNER` (a harness run sets it, its agent sessions inherit it), else the Claude Code session's `CLAUDE_CODE_SESSION_ID`. While the mark is fresh, a claim by another owner, or by none, is refused, and so is a `--claimed` move from another owner. A mark that names nobody (written before 0.10.2, or claimed from a console with neither id), a stale one, or one of a harness run whose process is gone holds nobody. Only the owner's own commands on the item keep its mark fresh (a fresh mark that names nobody, any session's), and only the named owner revives a stale one. `gcf release` stays the human's way out, also for a session whose id changed (`/clear`). Update together with gcf-harness-aif-ext 0.9.10: an older harness started from inside a Claude Code session would claim under that session's id, and its own agent would be refused.
56
+
57
+ ### 0.10.1
58
+
59
+ - `gcf board --json` has `extensions_error`: why `.ai-factory.json` is there but cannot be read (null otherwise). With such a file the board knows no harness and hides its run buttons; gcf-board 0.4.1 says so in its top bar.
60
+ - A `depends` cycle through a feature says "a feature waits for its children" only when a step of it is the feature waiting for a child, not when the feature is in it by `depends` alone.
61
+
53
62
  ### 0.10.0
54
63
 
55
64
  - `gcf board --json` is `schema: 3`: `domain` describes the whole GCF domain for a board (Methodology §11, Board-PRD decision 16). It names the harness (`gcf-harness` when the project has gcf-harness-aif-ext, else null), the agent's move `run` (offered first in `items[].moves` to a ready item without a green verify, only with the harness), every move's form with its full `ai-factory` words (`gcf …`) — the new item, the phase, the inbox, the answers, the run order and `depends` included —, the item's fields for the card and the drawer, its blocks (`sections`) and the Help terms. `depends` is offered to every item; `waits_for` is empty while a run drives the item. gcf-board 0.4.0 reads it; update both together.
@@ -115,7 +124,7 @@ On Windows, run `extension add` and `extension update` from PowerShell or cmd, n
115
124
 
116
125
  - `priority:` on an item: a rank, lower runs sooner. `ai-factory gcf prioritize <id> <id> …` ranks items in that order in one commit; `item new --priority <n>`. `gcf board --json` lists ranked items first and carries `priority`.
117
126
  - `ai-factory gcf question answer <q-id> --text="<answer>"` writes the human's answer into its record of `gcf/open-questions.md` and commits. An answered D1 no longer blocks its units; the next agent on the unit puts the answer into its slot (`answer: q-NNN`) and removes the record. `gcf board --json` questions carry `question`, `proposed`, `blocks` and `answer`.
118
- - `ai-factory gcf claim <id>` / `release <id>`: an agent session working an item in the main checkout marks it running. The session's own `context`, `plan check` and `verify` on the item keep the mark fresh (so do a harness run on main and its readset-guard hook), a move on the item clears it, and 2 hours without either expire it. The board and the audit read it as `running`, so a harness run does not take the item, and the core refuses any move on it but the session's own (`submit`, `close`, `block` with `--claimed`).
127
+ - `ai-factory gcf claim <id>` / `release <id>`: an agent session working an item in the main checkout marks it running. The session's own `context`, `plan check` and `verify` on the item keep the mark fresh (so do a harness run on main and its readset-guard hook), a move on the item clears it, and 2 hours without either expire it. The board and the audit read it as `running`, so a harness run does not take the item, and the core refuses any move on it but the session's own (`submit`, `close`, `block` with `--claimed`). The mark names its owner (`GCF_RUN_OWNER` of a harness run, else `CLAUDE_CODE_SESSION_ID`): another owner's claim and `--claimed` moves are refused while it is fresh.
119
128
  - `prioritize` leaves the rank of a ready item it does not name (a running one): the named items take the free ranks around it.
120
129
  - `run_mode: worktree | main` in `gcf/config.yml` (Methodology §7): a project whose agent works through an editor bound to the project folder sets `main`. `gcf board --json` carries it.
121
130
  - `/gcf-card` cuts several items along subsystem boundaries, marks two items of one subsystem that change different files `parallel: ok`, ranks them with `prioritize`, and keeps `depends` for real needs only.
package/extension.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
3
3
  "name": "gcf-aif-ext",
4
- "version": "0.10.0",
4
+ "version": "0.10.2",
5
5
  "description": "Game Context Framework for AI Factory",
6
6
  "skills": [
7
7
  "skills/gcf-init",
package/lib/board.js CHANGED
@@ -135,21 +135,36 @@ async function phaseOf(projectDir) {
135
135
 
136
136
  /**
137
137
  * The AI Factory extensions the project has, name → version, from `.ai-factory.json`: the board
138
- * shows which framework packages a project runs. `{}` when the file is missing or unreadable.
138
+ * shows which framework packages a project runs. `extensions` is `{}` when the file is missing
139
+ * or unreadable;
140
+ * `error` says why a file that is there cannot be read: the run buttons hide with no harness.
139
141
  */
140
142
  async function extensionsOf(projectDir) {
143
+ const file = path.join(path.resolve(projectDir), '.ai-factory.json');
144
+ let text;
141
145
  try {
142
- const cfg = JSON.parse(
143
- await readFile(path.join(path.resolve(projectDir), '.ai-factory.json'), 'utf8'),
144
- );
145
-
146
- return Object.fromEntries(
147
- (cfg.extensions ?? [])
148
- .filter((e) => typeof e?.name === 'string')
149
- .map((e) => [e.name, typeof e.version === 'string' ? e.version : null]),
150
- );
151
- } catch {
152
- return {};
146
+ text = await readFile(file, 'utf8');
147
+ } catch (e) {
148
+ return { extensions: {}, error: e.code === 'ENOENT' ? null : e.message };
149
+ }
150
+
151
+ try {
152
+ const cfg = JSON.parse(text);
153
+ if (cfg === null || typeof cfg !== 'object' || Array.isArray(cfg))
154
+ throw new Error('it is not a JSON object');
155
+ const list = cfg.extensions ?? [];
156
+ if (!Array.isArray(list)) throw new Error('"extensions" is not a list');
157
+
158
+ return {
159
+ extensions: Object.fromEntries(
160
+ list
161
+ .filter((e) => typeof e?.name === 'string')
162
+ .map((e) => [e.name, typeof e.version === 'string' ? e.version : null]),
163
+ ),
164
+ error: null,
165
+ };
166
+ } catch (e) {
167
+ return { extensions: {}, error: e.message };
153
168
  }
154
169
  }
155
170
 
@@ -294,7 +309,7 @@ export async function board(projectDir) {
294
309
  const root = path.join(path.resolve(projectDir), 'gcf');
295
310
  const ledger = await buildLedger(projectDir);
296
311
  const verified = verifiedOf(projectDir);
297
- const extensions = await extensionsOf(projectDir);
312
+ const { extensions, error: extensionsError } = await extensionsOf(projectDir);
298
313
  const harness = hasHarness(extensions);
299
314
  const items = [];
300
315
  for (const c of ledger.items)
@@ -331,6 +346,7 @@ export async function board(projectDir) {
331
346
  },
332
347
  phase: await phaseOf(projectDir),
333
348
  extensions,
349
+ extensions_error: extensionsError,
334
350
  // A malformed block reads with fields missing (live check names it): null, not absent.
335
351
  release: releaseOf(live.release),
336
352
  // The domain as data (Board-PRD decision 16): its columns, blocks, fields, moves and terms.
@@ -589,13 +589,23 @@ export function pathTo(graph, from, to, seen = new Set()) {
589
589
  return null;
590
590
  }
591
591
 
592
- /** Why a depends `cycle` (its ids, the first again at the end) never gets played. */
593
- export function cycleMessage(ledger, cycle) {
594
- const feature = cycle.some((id) => ledger.item(id)?.data.type === 'feature');
592
+ /**
593
+ * Why a depends `cycle` (its ids, the first again at the end) never gets played. The feature
594
+ * hint only when a step of the cycle is a feature waiting for a child: one in its `children`,
595
+ * or a new one the move is about to add (`children`, [feature, child] pairs).
596
+ */
597
+ export function cycleMessage(ledger, cycle, children = []) {
598
+ const childStep = cycle.slice(1).some((to, i) => {
599
+ const from = cycle[i];
600
+ const item = ledger.item(from);
601
+ const kids = item?.data.type === 'feature' ? (item.data.children ?? []) : [];
602
+
603
+ return kids.includes(to) || children.some(([f, c]) => f === from && c === to);
604
+ });
595
605
 
596
606
  return (
597
607
  `depends cycle ${cycle.join(' -> ')}: none of them can be played first` +
598
- (feature ? ' (a feature waits for its children)' : '')
608
+ (childStep ? ' (a feature waits for its children)' : '')
599
609
  );
600
610
  }
601
611
 
package/lib/main-lock.js CHANGED
@@ -14,7 +14,7 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
14
14
  export const lockFile = (projectDir) =>
15
15
  path.join(path.resolve(projectDir), '.gcf-session', 'main.lock');
16
16
 
17
- const alive = (pid) => {
17
+ export const alive = (pid) => {
18
18
  try {
19
19
  process.kill(pid, 0);
20
20
 
@@ -3,11 +3,13 @@
3
3
  // `/gcf-run` claims the item with a mark, the session's own gcf commands on the item keep it
4
4
  // fresh (and so do a harness run on main and the harness's readset-guard hook on each read),
5
5
  // and the move that ends the run clears it. A mark nobody refreshed for SESSION_TTL_MS is a
6
- // session that stopped: the item reads as not running again.
7
- import { existsSync, rmSync, statSync, utimesSync } from 'node:fs';
6
+ // session that stopped: the item reads as not running again. The mark names its owner, so a
7
+ // second session cannot take an item the first one works.
8
+ import { existsSync, readFileSync, rmSync, statSync, utimesSync } from 'node:fs';
8
9
  import { mkdir, writeFile } from 'node:fs/promises';
9
10
  import path from 'node:path';
10
11
  import { excludeSession } from './integrate.js';
12
+ import { alive, withMainLock } from './main-lock.js';
11
13
 
12
14
  // A run's default timeout: an agent can implement for long without a gcf command. The harness
13
15
  // and its readset-guard hook refresh a live session's mark meanwhile.
@@ -16,17 +18,57 @@ export const SESSION_TTL_MS = 120 * 60_000;
16
18
  const markOf = (projectDir, id) =>
17
19
  path.join(path.resolve(projectDir), '.gcf-session', 'runs', `${id}.session`);
18
20
 
19
- /** Mark item `id` as worked by this session. */
20
- export async function claimSession(projectDir, id) {
21
+ /**
22
+ * Who works an item: a harness run (`GCF_RUN_OWNER`, which its agent sessions inherit, a fresh
23
+ * one after a handoff included), else the Claude Code session; null when neither is known.
24
+ */
25
+ export const ownerOf = (env = process.env) =>
26
+ env.GCF_RUN_OWNER || env.CLAUDE_CODE_SESSION_ID || null;
27
+
28
+ /** The owner line of item `id`'s mark, fresh or not; null with none. */
29
+ function ownerLine(projectDir, id) {
30
+ try {
31
+ return readFileSync(markOf(projectDir, id), 'utf8').split('\n')[1]?.trim() || null;
32
+ } catch {
33
+ return null;
34
+ }
35
+ }
36
+
37
+ /** The owner a live mark names; null with no live mark, or one written with no owner. */
38
+ export const markOwner = (projectDir, id) =>
39
+ sessionActive(projectDir, id) ? ownerLine(projectDir, id) : null;
40
+
41
+ /** Whether `owner` is the session holding item `id`'s mark, or the mark names nobody. */
42
+ export function ownsMark(projectDir, id, owner = ownerOf()) {
43
+ const held = markOwner(projectDir, id);
44
+
45
+ return !held || held === owner;
46
+ }
47
+
48
+ /** Mark item `id` as worked by `owner`; refused while another owner's mark is fresh. */
49
+ export async function claimSession(projectDir, id, owner = ownerOf()) {
21
50
  const file = markOf(projectDir, id);
22
51
  await excludeSession(projectDir);
23
52
  await mkdir(path.dirname(file), { recursive: true });
24
- await writeFile(file, `${new Date().toISOString()}\n`);
53
+ // Under the main lock: two sessions claiming at once must not both pass the check.
54
+ await withMainLock(projectDir, async () => {
55
+ if (!ownsMark(projectDir, id, owner))
56
+ throw new Error(
57
+ `${id} is worked by another agent session (${markOwner(projectDir, id)}): leave it to ` +
58
+ `that session, or run ai-factory gcf release ${id} when no session works it`,
59
+ );
60
+ await writeFile(file, `${new Date().toISOString()}\n${owner ?? ''}\n`);
61
+ });
25
62
  }
26
63
 
27
- /** Keep a session's mark fresh: its own commands on the item call this; no mark, no-op. */
28
- export function touchSession(projectDir, id) {
64
+ /**
65
+ * Keep a session's mark fresh: its own commands on the item call this. Another owner's mark is
66
+ * left alone, and only its owner revives a mark gone stale; with no mark, a no-op.
67
+ */
68
+ export function touchSession(projectDir, id, owner = ownerOf()) {
29
69
  const file = markOf(projectDir, id);
70
+ const held = ownerLine(projectDir, id);
71
+ if (held ? held !== owner : !sessionActive(projectDir, id)) return;
30
72
  try {
31
73
  const now = new Date();
32
74
  utimesSync(file, now, now);
@@ -48,13 +90,20 @@ export function dropAgentSession(projectDir, id) {
48
90
  rmSync(path.join(path.dirname(markOf(projectDir, id)), `${id}.agent.json`), { force: true });
49
91
  }
50
92
 
51
- /** Whether a session works the item now: a mark refreshed within SESSION_TTL_MS. */
93
+ /**
94
+ * Whether a session works the item now: a mark refreshed within SESSION_TTL_MS, and not one of a
95
+ * harness run (`run:<pid>`) whose process is gone: a killed run does not hold its item.
96
+ */
52
97
  export function sessionActive(projectDir, id) {
53
98
  const file = markOf(projectDir, id);
54
99
  if (!existsSync(file)) return false;
55
100
  try {
56
- return Date.now() - statSync(file).mtimeMs < SESSION_TTL_MS;
101
+ if (Date.now() - statSync(file).mtimeMs >= SESSION_TTL_MS) return false;
57
102
  } catch {
58
103
  return false;
59
104
  }
105
+
106
+ const run = ownerLine(projectDir, id)?.match(/^run:(\d+)$/);
107
+
108
+ return !run || alive(Number(run[1]));
60
109
  }
package/lib/unit-ops.js CHANGED
@@ -134,7 +134,14 @@ function refuseFeatureCycle(ledger, feature, units) {
134
134
  for (const u of units)
135
135
  for (const d of graph.get(u.id) ?? []) {
136
136
  const loop = pathTo(graph, d, u.id);
137
- if (loop) throw new Error(cycleMessage(ledger, [u.id, ...loop]));
137
+ if (loop)
138
+ throw new Error(
139
+ cycleMessage(
140
+ ledger,
141
+ [u.id, ...loop],
142
+ units.map((x) => [feature, x.id]),
143
+ ),
144
+ );
138
145
  }
139
146
  }
140
147
 
package/lib/work-ops.js CHANGED
@@ -39,7 +39,7 @@ import { dropInbox } from './inbox.js';
39
39
  import { cycleMessage, dependsGraph, pathTo } from './design-check.js';
40
40
  import { refuseByPhase } from './phase.js';
41
41
  import { locked, runHolder } from './main-lock.js';
42
- import { dropAgentSession, releaseSession, sessionActive } from './session-mark.js';
42
+ import { dropAgentSession, ownsMark, releaseSession, sessionActive } from './session-mark.js';
43
43
  import { dropStamp, unverifiedProblem } from './verify-stamp.js';
44
44
 
45
45
  /**
@@ -176,8 +176,8 @@ function refuseRunning(projectDir, id, self = process.env.GCF_RUN_ITEM ?? null)
176
176
  `run is going, delete .gcf-session/runs/${id}.lock`,
177
177
  );
178
178
  // The session that claimed the item moves it itself (GCF_RUN_ITEM, set by `--claimed` or by
179
- // a harness run on main); anyone else waits, as for a run lock.
180
- if (sessionActive(projectDir, id) && self !== id)
179
+ // a harness run on main, and the mark's owner); anyone else waits, as for a run lock.
180
+ if (sessionActive(projectDir, id) && (self !== id || !ownsMark(projectDir, id)))
181
181
  throw new Error(
182
182
  `${id} is worked by an agent session (gcf claim): wait until it moves the item, or run ` +
183
183
  `ai-factory gcf release ${id} when no session works it`,
@@ -852,7 +852,7 @@ function checkDepends(ledger, id, depends, { added = depends, parent = null } =
852
852
  if (parent) graph.set(parent, [...(graph.get(parent) ?? []), id]);
853
853
  for (const d of added) {
854
854
  const loop = pathTo(graph, d, id);
855
- if (loop) throw new Error(cycleMessage(ledger, [id, ...loop]));
855
+ if (loop) throw new Error(cycleMessage(ledger, [id, ...loop], [[parent, id]]));
856
856
  }
857
857
  }
858
858
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gcf-aif-ext",
3
- "version": "0.10.0",
3
+ "version": "0.10.2",
4
4
  "description": "Game Context Framework for AI Factory",
5
5
  "type": "module",
6
6
  "license": "MIT",