aligndev 0.28.0 → 0.28.1

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
@@ -12,15 +12,16 @@ You talk to an **assistant**, the way you would to a developer on your team. It
12
12
 
13
13
  For each task, the assistant:
14
14
 
15
- 1. Discusses the task with the agent and has it write a **spec**.
16
- 2. Has it write the **plans**.
17
- 3. Has the plans **executed** in a fresh session.
18
- 4. Has a **code review** done in another session.
19
- 5. Has the review findings **fixed** in yet another session.
20
- 6. For UI changes, **tests manually** and checks the dev-server logs.
15
+ 1. Sets up the task's **workspace**.
16
+ 2. Refreshes the default branch and **merges** it into the task branch.
17
+ 3. Discusses the task with the agent and has it write a **spec**.
18
+ 4. Has it write the **plans**.
19
+ 5. Has the plans **executed** in a fresh session.
20
+ 6. **Tests manually**, takes **screenshots** of UI changes, and checks the dev-server logs.
21
21
  7. Has fixes made as needed.
22
- 8. Takes **screenshots** for good measure.
23
- 9. Has the agent **open a draft PR**.
22
+ 8. Has a **code review** done in another session.
23
+ 9. Has the review findings **fixed** in yet another session.
24
+ 10. Has the agent **open a PR**.
24
25
 
25
26
  A task can also start at any intermediate step.
26
27
 
@@ -9,6 +9,7 @@ import { type RunConfig } from "./run-agent.js";
9
9
  import { type SessionRecord } from "./session-file.js";
10
10
  export interface CodeContext {
11
11
  cwd: string;
12
+ home: string;
12
13
  env: NodeJS.ProcessEnv;
13
14
  stdout: Output;
14
15
  stderr: Output;
@@ -60,7 +61,7 @@ export interface SessionArgs {
60
61
  export declare function runCode(tokens: string[], loadSettings: () => LoadedConfig, ctx: CodeContext): Promise<number>;
61
62
  export declare function parseCodeArgs(tokens: string[], aligndev: string): CodeCommand;
62
63
  export declare function validateSessionArgs(args: SessionArgs, models: readonly string[] | undefined): string | undefined;
63
- export declare function checkLaunchGuards(args: SessionArgs, agent: CodingAgent, realCwd: string, ticket: string | undefined, records: SessionRecord[], previous?: SessionRecord): string | undefined;
64
+ export declare function checkLaunchGuards(args: SessionArgs, agent: CodingAgent, realCwd: string, ticket: string | undefined, records: SessionRecord[], machineId: string, previous?: SessionRecord): string | undefined;
64
65
  export declare function resolveTicket(args: SessionArgs, records: SessionRecord[]): string | undefined;
65
66
  export interface RunInput {
66
67
  args: SessionArgs;
@@ -7,11 +7,12 @@ import { errorMessage } from "../errors.js";
7
7
  import { companionInUse, readProjectReport, } from "../project/layout.js";
8
8
  import { validateEffectivePlans } from "../project/plans.js";
9
9
  import { createAgentAdapter } from "./coding-agent.js";
10
+ import { readMachineId } from "./machine-id.js";
10
11
  import { expandModelAlias, resolveModels } from "./models.js";
11
12
  import { describeNativeStorage } from "./native-context.js";
12
13
  import { buildPrompt, PROTOCOLS } from "./prompt.js";
13
14
  import { runAgent } from "./run-agent.js";
14
- import { applyCompletion, createSessionFile, findNewestSessionFile, listSessionRecords, readPidStartTime, reconcileSessionFile, RESULT_MARKER, } from "./session-file.js";
15
+ import { applyCompletion, completedSessionPath, createSessionFile, findNewestSessionFile, listSessionRecords, readPidStartTime, reconcileSessionFile, RESULT_MARKER, } from "./session-file.js";
15
16
  // Distinct from 1 (ordinary run failure) so a script can branch on an auth failure that needs an
16
17
  // operator re-login rather than a retry.
17
18
  const EXIT_AUTH_REQUIRED = 2;
@@ -49,7 +50,8 @@ export async function runCode(tokens, loadSettings, ctx) {
49
50
  const report = readReport(ctx);
50
51
  if (command.kind === "session")
51
52
  validateEffectivePlans(ctx);
52
- const records = command.kind === "session" ? listSessionRecords(report.locations._aligndev.path) : [];
53
+ const tree = command.kind === "session" ? sessionTreeOf(report, ctx) : undefined;
54
+ const records = tree === undefined ? [] : listSessionRecords(tree.sessionsDir, tree.machineId);
53
55
  const args = command.kind === "session" ? command.args : undefined;
54
56
  const previous = args?.resume === undefined
55
57
  ? undefined
@@ -75,7 +77,9 @@ export async function runCode(tokens, loadSettings, ctx) {
75
77
  ctx.stderr.write(`${validationError}\n`);
76
78
  return 1;
77
79
  }
78
- return await runSession(command.args, code, ctx, report, records, previous);
80
+ if (tree === undefined)
81
+ throw new Error("Missing session tree.");
82
+ return await runSession(command.args, code, ctx, report, tree, records, previous);
79
83
  }
80
84
  catch (error) {
81
85
  ctx.stderr.write(`${errorMessage(error)}\n`);
@@ -83,10 +87,9 @@ export async function runCode(tokens, loadSettings, ctx) {
83
87
  }
84
88
  }
85
89
  function showStatus(ctx, target, includeResult) {
86
- const tree = sessionTreeOf(readReport(ctx), ctx.cwd);
87
- const sessionFilePath = resolveStatusTargetSessionFile(tree, target);
88
- const completion = reconcileSessionFile(sessionFilePath);
89
- ctx.stdout.write(renderSessionStatus(tree.cwd, sessionFilePath, completion.frontmatter));
90
+ const tree = sessionTreeOf(readReport(ctx), ctx);
91
+ const completion = reconcileSessionFile(resolveStatusTargetSessionFile(tree, target), tree.machineId);
92
+ ctx.stdout.write(renderSessionStatus(tree.cwd, completion.path, completion.frontmatter));
90
93
  if (includeResult &&
91
94
  completion.frontmatter.status !== "running" &&
92
95
  completion.result !== undefined) {
@@ -100,10 +103,11 @@ function readReport(ctx) {
100
103
  throw new Error(report.error);
101
104
  return report;
102
105
  }
103
- function sessionTreeOf(report, cwd) {
106
+ function sessionTreeOf(report, ctx) {
104
107
  return {
105
- cwd: realpathSync(cwd),
108
+ cwd: realpathSync(ctx.cwd),
106
109
  sessionsDir: report.locations._aligndev.path,
110
+ machineId: readMachineId(ctx.home),
107
111
  };
108
112
  }
109
113
  async function showQuota(ctx, code) {
@@ -139,7 +143,7 @@ function resolveStatusTargetSessionFile(tree, target) {
139
143
  // A run tagged with `--meta <key>` is found by that key alone: the session tree is shared across
140
144
  // worktrees, so its newest run may belong to another thread.
141
145
  function resolveMetaSessionFile(tree, meta) {
142
- const matches = listSessionRecords(tree.sessionsDir).filter((record) => record.frontmatter.meta === meta);
146
+ const matches = listSessionRecords(tree.sessionsDir, tree.machineId).filter((record) => record.frontmatter.meta === meta);
143
147
  if (matches.length === 0)
144
148
  throw new Error(`Error: no session file with meta "${meta}".`);
145
149
  const newest = matches.reduce((a, b) => a.frontmatter.startedAt >= b.frontmatter.startedAt ? a : b);
@@ -153,15 +157,20 @@ function loadMessage(args, cwd) {
153
157
  }
154
158
  args.message = readFileSync(args.messageFile === "-" ? 0 : resolve(cwd, args.messageFile), "utf8");
155
159
  }
160
+ // A caller may retain the `.running.md` path of a run that has ended since: it resolves to the
161
+ // completed file.
156
162
  function resolveStatusSessionFile(tree, input) {
157
- const sessionFilePath = resolve(tree.cwd, input);
163
+ const requestedPath = resolve(tree.cwd, input);
158
164
  const sessionsDir = displayPath(tree.cwd, tree.sessionsDir);
159
- if (!isSessionFilePath(tree.sessionsDir, sessionFilePath)) {
165
+ if (!isSessionFilePath(tree.sessionsDir, requestedPath)) {
160
166
  throw new Error(`Error: status requires a session file under ${sessionsDir}/_aligndev/ or ` +
161
167
  `${sessionsDir}/<ticket>/_aligndev/.`);
162
168
  }
169
+ const sessionFilePath = existsSync(requestedPath)
170
+ ? requestedPath
171
+ : completedSessionPath(requestedPath);
163
172
  if (!existsSync(sessionFilePath)) {
164
- throw new Error(`Error: session file not found: ${displayPath(tree.cwd, sessionFilePath)}`);
173
+ throw new Error(`Error: session file not found: ${displayPath(tree.cwd, requestedPath)}`);
165
174
  }
166
175
  if (!isSessionFilePath(realpathSync(tree.sessionsDir), realpathSync(sessionFilePath))) {
167
176
  throw new Error(`Error: the session file resolves outside ${sessionsDir}/.`);
@@ -198,6 +207,7 @@ function renderSessionStatus(cwd, sessionFilePath, frontmatter) {
198
207
  `model: ${frontmatter.model ?? ""}`,
199
208
  `status: ${frontmatter.status}`,
200
209
  `pid: ${frontmatter.pid ?? ""}`,
210
+ `machineId: ${frontmatter.machineId ?? ""}`,
201
211
  `startedAt: ${frontmatter.startedAt}`,
202
212
  `endedAt: ${frontmatter.endedAt ?? ""}`,
203
213
  `exitReason: ${frontmatter.exitReason ?? ""}`,
@@ -379,17 +389,16 @@ function isPathSafeTicket(ticket) {
379
389
  // agent's background task) — aligndev owns no backgrounding or callback of its own. The per-run session
380
390
  // file is the durable result handoff: on completion the frontmatter carries the session id and
381
391
  // status, and the `---- Result ----` block carries the outcome for a waking caller (or a human).
382
- async function runSession(args, code, ctx, report, records, previous) {
392
+ async function runSession(args, code, ctx, report, tree, records, previous) {
383
393
  const { cwd, env, stdout, stderr, forms, alignfirstCommand, modelResolver } = ctx;
384
394
  const { agent } = code;
385
- const tree = sessionTreeOf(report, cwd);
386
395
  const resolvedTicket = args.noTicket
387
396
  ? undefined
388
397
  : (args.ticket ??
389
398
  (args.resume === undefined
390
399
  ? inferTicketFromMessage(args.message ?? "")
391
400
  : (previous?.frontmatter.ticket ?? undefined)));
392
- const guardError = checkLaunchGuards(args, agent, tree.cwd, resolvedTicket, records, previous);
401
+ const guardError = checkLaunchGuards(args, agent, tree.cwd, resolvedTicket, records, tree.machineId, previous);
393
402
  if (guardError) {
394
403
  stderr.write(`${guardError}\n`);
395
404
  return 1;
@@ -410,7 +419,16 @@ async function runSession(args, code, ctx, report, records, previous) {
410
419
  const contextContent = args.resume === undefined && companionInUse(report, CONTEXT_COMPANION_ITEMS)
411
420
  ? loadContext(alignfirstCommand, cwd, env)
412
421
  : undefined;
413
- const sessionFilePath = createSessionFile(tree.sessionsDir, ticket, now, buildFrontmatter({ args, agent, profile: code.profile, model, now, realCwd: tree.cwd, ticket }));
422
+ const sessionFilePath = createSessionFile(tree.sessionsDir, ticket, now, buildFrontmatter({
423
+ args,
424
+ agent,
425
+ profile: code.profile,
426
+ model,
427
+ now,
428
+ realCwd: tree.cwd,
429
+ ticket,
430
+ machineId: tree.machineId,
431
+ }));
414
432
  stdout.write(`Session file: ${displayPath(tree.cwd, sessionFilePath)}\n\n`);
415
433
  let executableModel;
416
434
  try {
@@ -425,14 +443,14 @@ async function runSession(args, code, ctx, report, records, previous) {
425
443
  (agent === "codex"
426
444
  ? " For Codex aliases, update the Codex CLI or select an explicit full model slug."
427
445
  : "");
428
- applyCompletion(sessionFilePath, {
446
+ const completedPath = applyCompletion(sessionFilePath, {
429
447
  status: "failed",
430
448
  endedAt: new Date().toISOString(),
431
449
  exitReason: "error",
432
450
  sessionId: args.resume ?? null,
433
451
  result: message,
434
452
  });
435
- writeFailureDiagnostic(ctx, sessionFilePath, message);
453
+ writeFailureDiagnostic(ctx, completedPath, message);
436
454
  return 1;
437
455
  }
438
456
  const runConfig = buildRunConfig({
@@ -449,11 +467,12 @@ async function runSession(args, code, ctx, report, records, previous) {
449
467
  });
450
468
  createMissingCompanion(report);
451
469
  const result = await runAgent(runConfig, createAgentAdapter(agent), stdout);
470
+ const completedPath = completedSessionPath(sessionFilePath);
452
471
  if (args.resume === undefined && result.sessionId) {
453
472
  stdout.write(`\nSession ID: ${result.sessionId}\n`);
454
473
  }
455
474
  if (result.authRequired) {
456
- writeFailureDiagnostic(ctx, sessionFilePath, `${nativeContext(code)} not authenticated — an administrator must re-login ` +
475
+ writeFailureDiagnostic(ctx, completedPath, `${nativeContext(code)} not authenticated — an administrator must re-login ` +
457
476
  "with the same effective environment as the child (apply profile unset/env/configDir, " +
458
477
  "including HOME, PATH and credential routing), from the same working directory. " +
459
478
  `Then use ${authenticationInstruction(agent)}. A bare login in another shell may use a different account.`);
@@ -461,7 +480,7 @@ async function runSession(args, code, ctx, report, records, previous) {
461
480
  }
462
481
  if (result.status === "succeeded")
463
482
  return 0;
464
- writeFailureDiagnostic(ctx, sessionFilePath, `${nativeContext(code)}: ${failureDiagnostic(agent, result.result)}${args.resume === undefined ? "" : " Check that the native conversation exists in this configuration; select the correct --profile or start a new session. No account fallback was attempted."}`);
483
+ writeFailureDiagnostic(ctx, completedPath, `${nativeContext(code)}: ${failureDiagnostic(agent, result.result)}${args.resume === undefined ? "" : " Check that the native conversation exists in this configuration; select the correct --profile or start a new session. No account fallback was attempted."}`);
465
484
  return 1;
466
485
  }
467
486
  function nativeContext(code) {
@@ -491,7 +510,7 @@ function failureDiagnostic(agent, result) {
491
510
  }
492
511
  // Fail-fast launch guards, run against the (healed) session records before anything is written.
493
512
  // Returns the error to print, or `undefined` when the launch may proceed.
494
- export function checkLaunchGuards(args, agent, realCwd, ticket, records, previous) {
513
+ export function checkLaunchGuards(args, agent, realCwd, ticket, records, machineId, previous) {
495
514
  if (args.resume !== undefined) {
496
515
  // A resumed run writes a new session file carrying the same sessionId as the original, so one
497
516
  // id can match several records — a running status on any of them blocks.
@@ -500,8 +519,8 @@ export function checkLaunchGuards(args, agent, realCwd, ticket, records, previou
500
519
  return unknownResumeError(args.resume, records);
501
520
  const running = matches.find((r) => r.frontmatter.status === "running");
502
521
  if (running) {
503
- return (`Error: session ${args.resume} is still running (pid ${running.frontmatter.pid}); ` +
504
- "wait for it to finish or kill it.");
522
+ return (`Error: session ${args.resume} is still running (${running.path}, pid ${running.frontmatter.pid}); ` +
523
+ `${runningRecordAdvice(running, machineId)}.`);
505
524
  }
506
525
  const latest = previous ?? latestRecord(matches);
507
526
  if (latest.frontmatter.agent === null) {
@@ -523,10 +542,10 @@ export function checkLaunchGuards(args, agent, realCwd, ticket, records, previou
523
542
  const active = records.filter((r) => r.frontmatter.status === "running" && r.frontmatter.protocol !== null);
524
543
  const sameWorktree = active.find((r) => r.frontmatter.cwd === realCwd);
525
544
  if (sameWorktree)
526
- return busyProtocolError(sameWorktree, "in this worktree");
545
+ return busyProtocolError(sameWorktree, "in this worktree", machineId);
527
546
  const sameTicket = ticket === undefined ? undefined : active.find((r) => r.frontmatter.ticket === ticket);
528
547
  if (sameTicket)
529
- return busyProtocolError(sameTicket, `on ticket ${ticket}`);
548
+ return busyProtocolError(sameTicket, `on ticket ${ticket}`, machineId);
530
549
  }
531
550
  return;
532
551
  }
@@ -540,10 +559,16 @@ function sameRealDirectory(recorded, realCwd) {
540
559
  return false;
541
560
  }
542
561
  }
543
- function busyProtocolError(record, scope) {
562
+ function busyProtocolError(record, scope, machineId) {
544
563
  return (`Error: a ${record.frontmatter.protocol} protocol run is already active ${scope} ` +
545
564
  `(${record.path}, pid ${record.frontmatter.pid}); one protocol run at a time per worktree ` +
546
- "and per ticket.");
565
+ `and per ticket; ${runningRecordAdvice(record, machineId)}.`);
566
+ }
567
+ function runningRecordAdvice(record, machineId) {
568
+ return record.frontmatter.machineId === machineId
569
+ ? "wait for it to finish"
570
+ : "this record was written by another machine or before machine identities: check it on its machine, " +
571
+ "or set its `status` by hand once the run has ended";
547
572
  }
548
573
  // The newest record of a non-empty list: a resumed session has one record per run.
549
574
  function latestRecord(records) {
@@ -621,6 +646,7 @@ function buildFrontmatter(input) {
621
646
  meta: args.meta ?? null,
622
647
  pid: process.pid,
623
648
  pidStartTime: readPidStartTime(process.pid),
649
+ machineId: input.machineId,
624
650
  cwd: input.realCwd,
625
651
  startedAt: now.toISOString(),
626
652
  endedAt: null,
@@ -0,0 +1 @@
1
+ export declare function readMachineId(home: string): string;
@@ -0,0 +1,34 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
3
+ import { dirname, join } from "node:path";
4
+ import { errorMessage } from "../errors.js";
5
+ export function readMachineId(home) {
6
+ const path = join(home, ".alignfirst", "machine-id");
7
+ try {
8
+ const id = readOrCreateMachineId(path).trim();
9
+ if (id === "")
10
+ throw new Error("file is empty");
11
+ return id;
12
+ }
13
+ catch (error) {
14
+ throw new Error(`Could not read machine identity at ${path}: ${errorMessage(error)}`);
15
+ }
16
+ }
17
+ function readOrCreateMachineId(path) {
18
+ try {
19
+ return readFileSync(path, "utf8");
20
+ }
21
+ catch (error) {
22
+ if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT")
23
+ throw error;
24
+ }
25
+ mkdirSync(dirname(path), { recursive: true });
26
+ try {
27
+ writeFileSync(path, randomUUID(), { flag: "wx" });
28
+ }
29
+ catch (error) {
30
+ if (!(error instanceof Error) || !("code" in error) || error.code !== "EEXIST")
31
+ throw error;
32
+ }
33
+ return readFileSync(path, "utf8");
34
+ }
@@ -11,6 +11,7 @@ export interface SessionFrontmatter {
11
11
  meta: string | null;
12
12
  pid: number | null;
13
13
  pidStartTime: string | null;
14
+ machineId: string | null;
14
15
  cwd: string | null;
15
16
  startedAt: string;
16
17
  endedAt: string | null;
@@ -21,6 +22,7 @@ export interface SessionFrontmatter {
21
22
  }
22
23
  export declare const RESULT_MARKER = "\n---- Result ----\n";
23
24
  export declare function createSessionFile(sessionsDir: string, ticket: string | undefined, now: Date, frontmatter: SessionFrontmatter): string;
25
+ export declare function completedSessionPath(sessionFilePath: string): string;
24
26
  export declare function resolveSessionFilePath(sessionsDir: string, ticket: string | undefined, now: Date, fileExists?: (path: string) => boolean): string;
25
27
  export declare function writeInitialSessionFile(sessionFilePath: string, frontmatter: SessionFrontmatter): void;
26
28
  export interface CompletionUpdate {
@@ -34,20 +36,23 @@ export interface CompletionUpdate {
34
36
  contextTokensError?: string | null;
35
37
  }
36
38
  export declare function formatResults(earlier: readonly string[], last: string): string;
37
- export declare function applyCompletion(sessionFilePath: string, update: CompletionUpdate): void;
39
+ export declare function applyCompletion(sessionFilePath: string, update: CompletionUpdate): string;
38
40
  export declare function appendTranscript(sessionFilePath: string, text: string): void;
39
41
  export interface SessionCompletion {
40
42
  frontmatter: SessionFrontmatter;
41
43
  result: string | undefined;
42
44
  }
43
45
  export declare function readCompletion(sessionFilePath: string): SessionCompletion;
44
- export declare function reconcileSessionFile(sessionFilePath: string, now?: Date): SessionCompletion;
46
+ export interface ReconciledSession extends SessionCompletion {
47
+ path: string;
48
+ }
49
+ export declare function reconcileSessionFile(sessionFilePath: string, machineId: string, now?: Date): ReconciledSession;
45
50
  export declare function readPidStartTime(pid: number): string | null;
46
51
  export interface SessionRecord {
47
52
  path: string;
48
53
  frontmatter: SessionFrontmatter;
49
54
  }
50
- export declare function listSessionRecords(sessionsDir: string): SessionRecord[];
55
+ export declare function listSessionRecords(sessionsDir: string, machineId: string): SessionRecord[];
51
56
  export declare function findNewestSessionFile(dir: string): string | undefined;
52
57
  export declare function serializeFrontmatter(frontmatter: SessionFrontmatter): string;
53
58
  export declare function parseFrontmatter(block: string): SessionFrontmatter;
@@ -1,13 +1,19 @@
1
- import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from "node:fs";
1
+ import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
2
2
  import { dirname, join } from "node:path";
3
3
  export const RESULT_MARKER = "\n---- Result ----\n";
4
4
  const LATER_RESULT_SEPARATOR = "\n\n---- Later result ----\n\n";
5
+ // A run is written as `<stamp>.running.md` and renamed to `<stamp>.md` when it ends, so the
6
+ // work-files sync can leave running logs out by name. Records written before this convention keep
7
+ // their name and their `running` status until their run ends.
8
+ const RUNNING_SUFFIX = ".running.md";
5
9
  export function createSessionFile(sessionsDir, ticket, now, frontmatter) {
6
10
  const dir = join(sessionsDir, ...(ticket === undefined ? [] : [ticket]), "_aligndev");
7
11
  mkdirSync(dir, { recursive: true });
8
12
  const stamp = formatStamp(now);
9
13
  for (let suffix = 1;; ++suffix) {
10
14
  const path = sessionFileCandidate(dir, stamp, suffix);
15
+ if (existsSync(completedSessionPath(path)))
16
+ continue;
11
17
  try {
12
18
  claimSessionFile(path, frontmatter);
13
19
  return path;
@@ -19,7 +25,12 @@ export function createSessionFile(sessionsDir, ticket, now, frontmatter) {
19
25
  }
20
26
  }
21
27
  function sessionFileCandidate(dir, stamp, suffix) {
22
- return join(dir, `${stamp}${suffix === 1 ? "" : `-${suffix}`}.md`);
28
+ return join(dir, `${stamp}${suffix === 1 ? "" : `-${suffix}`}${RUNNING_SUFFIX}`);
29
+ }
30
+ export function completedSessionPath(sessionFilePath) {
31
+ if (!sessionFilePath.endsWith(RUNNING_SUFFIX))
32
+ return sessionFilePath;
33
+ return `${sessionFilePath.slice(0, -RUNNING_SUFFIX.length)}.md`;
23
34
  }
24
35
  function claimSessionFile(path, frontmatter) {
25
36
  writeFileSync(path, `${serializeFrontmatter(frontmatter)}\n`, { flag: "wx" });
@@ -30,7 +41,8 @@ export function resolveSessionFilePath(sessionsDir, ticket, now, fileExists = ex
30
41
  const dir = join(sessionsDir, ...(ticket === undefined ? [] : [ticket]), "_aligndev");
31
42
  const stamp = formatStamp(now);
32
43
  let suffix = 1;
33
- while (fileExists(sessionFileCandidate(dir, stamp, suffix)))
44
+ while (fileExists(sessionFileCandidate(dir, stamp, suffix)) ||
45
+ fileExists(completedSessionPath(sessionFileCandidate(dir, stamp, suffix))))
34
46
  ++suffix;
35
47
  return sessionFileCandidate(dir, stamp, suffix);
36
48
  }
@@ -43,8 +55,9 @@ export function writeInitialSessionFile(sessionFilePath, frontmatter) {
43
55
  export function formatResults(earlier, last) {
44
56
  return [...earlier, last].join(LATER_RESULT_SEPARATOR);
45
57
  }
46
- // Appends the result block, then rewrites the frontmatter in place. Append-first keeps the tailed
47
- // transcript intact until the single terminal rewrite.
58
+ // Appends the result block, then rewrites the frontmatter in place, then renames the file to its
59
+ // completed name. Returns that name. Append-first keeps the tailed transcript intact until the
60
+ // single terminal rewrite.
48
61
  export function applyCompletion(sessionFilePath, update) {
49
62
  const content = readFileSync(sessionFilePath, "utf-8");
50
63
  const { frontmatter, body } = splitSessionFile(content);
@@ -60,6 +73,10 @@ export function applyCompletion(sessionFilePath, update) {
60
73
  };
61
74
  const resultBlock = `${RESULT_MARKER}\n${update.result}\n`;
62
75
  writeFileSync(sessionFilePath, `${serializeFrontmatter(updated)}\n${body}${resultBlock}`);
76
+ const completedPath = completedSessionPath(sessionFilePath);
77
+ if (completedPath !== sessionFilePath)
78
+ renameSync(sessionFilePath, completedPath);
79
+ return completedPath;
63
80
  }
64
81
  export function appendTranscript(sessionFilePath, text) {
65
82
  writeFileSync(sessionFilePath, text, { flag: "a" });
@@ -76,13 +93,13 @@ export function readCompletion(sessionFilePath) {
76
93
  const result = markerIndex === -1 ? undefined : content.slice(markerIndex + RESULT_MARKER.length).trim();
77
94
  return { frontmatter, result };
78
95
  }
79
- export function reconcileSessionFile(sessionFilePath, now = new Date()) {
96
+ export function reconcileSessionFile(sessionFilePath, machineId, now = new Date()) {
80
97
  const completion = readCompletion(sessionFilePath);
81
- const update = interruptedCompletion(completion.frontmatter, now);
98
+ const update = interruptedCompletion(completion.frontmatter, machineId, now);
82
99
  if (!update)
83
- return completion;
84
- applyCompletion(sessionFilePath, update);
100
+ return { ...completion, path: sessionFilePath };
85
101
  return {
102
+ path: applyCompletion(sessionFilePath, update),
86
103
  frontmatter: {
87
104
  ...completion.frontmatter,
88
105
  status: update.status,
@@ -92,8 +109,10 @@ export function reconcileSessionFile(sessionFilePath, now = new Date()) {
92
109
  result: update.result,
93
110
  };
94
111
  }
95
- function interruptedCompletion(frontmatter, now) {
96
- if (frontmatter.status !== "running" || isRecordedProcessAlive(frontmatter))
112
+ function interruptedCompletion(frontmatter, machineId, now) {
113
+ if (frontmatter.status !== "running" ||
114
+ frontmatter.machineId !== machineId ||
115
+ !isRecordedProcessGone(frontmatter))
97
116
  return;
98
117
  return {
99
118
  status: "failed",
@@ -103,22 +122,19 @@ function interruptedCompletion(frontmatter, now) {
103
122
  result: `Sealed as interrupted: process ${frontmatter.pid ?? "(unknown)"} is gone.`,
104
123
  };
105
124
  }
106
- function isRecordedProcessAlive(frontmatter) {
107
- if (frontmatter.pid === null || !isPidAlive(frontmatter.pid))
125
+ function isRecordedProcessGone(frontmatter) {
126
+ if (frontmatter.pid === null)
108
127
  return false;
109
- if (frontmatter.pidStartTime === null)
110
- return true;
111
- const currentStartTime = readPidStartTime(frontmatter.pid);
112
- return currentStartTime === null || currentStartTime === frontmatter.pidStartTime;
113
- }
114
- function isPidAlive(pid) {
115
128
  try {
116
- process.kill(pid, 0);
117
- return true;
129
+ process.kill(frontmatter.pid, 0);
118
130
  }
119
- catch (err) {
120
- return err.code !== "ESRCH";
131
+ catch (error) {
132
+ return error instanceof Error && "code" in error && error.code === "ESRCH";
121
133
  }
134
+ if (frontmatter.pidStartTime === null)
135
+ return false;
136
+ const currentStartTime = readPidStartTime(frontmatter.pid);
137
+ return currentStartTime !== null && currentStartTime !== frontmatter.pidStartTime;
122
138
  }
123
139
  export function readPidStartTime(pid) {
124
140
  if (process.platform !== "linux")
@@ -135,10 +151,9 @@ export function readPidStartTime(pid) {
135
151
  // Lists every active session record: `<sessionsDir>/_aligndev/*.md` plus
136
152
  // `<sessionsDir>/<ticket>/_aligndev/*.md`. Archived tickets move under `_archives/` and leave the
137
153
  // registry. The session files are the registry — no separate registry file.
138
- // Self-healing: a `running` record whose pid is gone is a stale leftover from an interrupted run;
139
- // it gets sealed in passing so the launch guards never block on dead state. The returned records
140
- // reflect the post-healing state.
141
- export function listSessionRecords(sessionsDir) {
154
+ // Seals only this installation's conclusively dead runs. Foreign, legacy and uncertain records
155
+ // stay untouched and continue to block launches.
156
+ export function listSessionRecords(sessionsDir, machineId) {
142
157
  const sessionDirs = [join(sessionsDir, "_aligndev")];
143
158
  for (const entry of readEntries(sessionsDir)) {
144
159
  if (entry.isDirectory() && !entry.name.startsWith("_")) {
@@ -150,10 +165,9 @@ export function listSessionRecords(sessionsDir) {
150
165
  for (const entry of readEntries(dir)) {
151
166
  if (!entry.isFile() || !entry.name.endsWith(".md"))
152
167
  continue;
153
- const path = join(dir, entry.name);
154
- const completion = reconcileSessionFileOrSkip(path);
168
+ const completion = reconcileSessionFileOrSkip(join(dir, entry.name), machineId);
155
169
  if (completion)
156
- records.push({ path, frontmatter: completion.frontmatter });
170
+ records.push({ path: completion.path, frontmatter: completion.frontmatter });
157
171
  }
158
172
  }
159
173
  return records;
@@ -165,7 +179,7 @@ export function findNewestSessionFile(dir) {
165
179
  for (const entry of readEntries(dir)) {
166
180
  if (!entry.isFile())
167
181
  continue;
168
- const match = /^(\d{8}-\d{6})(?:-(\d+))?\.md$/.exec(entry.name);
182
+ const match = /^(\d{8}-\d{6})(?:-(\d+))?(?:\.running)?\.md$/.exec(entry.name);
169
183
  if (!match)
170
184
  continue;
171
185
  const stamp = match[1];
@@ -189,9 +203,9 @@ function readEntries(dir) {
189
203
  }
190
204
  }
191
205
  // A malformed file (e.g. missing its frontmatter block) must not block every future launch.
192
- function reconcileSessionFileOrSkip(path) {
206
+ function reconcileSessionFileOrSkip(path, machineId) {
193
207
  try {
194
- return reconcileSessionFile(path);
208
+ return reconcileSessionFile(path, machineId);
195
209
  }
196
210
  catch {
197
211
  return;
@@ -239,6 +253,7 @@ export function parseFrontmatter(block) {
239
253
  meta: map.meta ?? null,
240
254
  pid: parsePid(map.pid),
241
255
  pidStartTime: map.pidStartTime ?? null,
256
+ machineId: map.machineId ?? null,
242
257
  cwd: map.cwd ?? null,
243
258
  startedAt: map.startedAt ?? "",
244
259
  endedAt: map.endedAt ?? null,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "aligndev",
3
- "version": "0.28.0",
3
+ "version": "0.28.1",
4
4
  "license": "CC0-1.0",
5
5
  "author": "Thomas MUR",
6
6
  "description": "The AlignDev CLI: the assistant's playbook, coding-agent delegation, and project inventory.",
@@ -13,7 +13,7 @@ Run `{{ALIGNDEV}} code` from the root of the selected worktree, so the agent wor
13
13
 
14
14
  {{ALIGNFIRST_SETUP}}
15
15
 
16
- Each ticketed run writes `.plans/<ticket>/_aligndev/<stamp>.md`. This file is the durable record of the run. It may live in the project's companion directory; the `sessionFile:` line of `{{ALIGNDEV}} code status` gives the actual path. Its frontmatter carries `status` (`running` → `succeeded`/`failed`) and the `sessionId`, and the `---- Result ----` block holds the outcome. A run that answers more than once lists each response oldest first, separated by `---- Later result ----`. A substantive report may precede a short later acknowledgement; report the substantive outcome.
16
+ Each ticketed run writes `.plans/<ticket>/_aligndev/<stamp>.running.md`, renamed to `<stamp>.md` when the run ends; `{{ALIGNDEV}} code status` accepts either name. This file is the durable record of the run. It may live in the project's companion directory; the `sessionFile:` line of `{{ALIGNDEV}} code status` gives the actual path. Its frontmatter carries `status` (`running` → `succeeded`/`failed`) and the `sessionId`, and the `---- Result ----` block holds the outcome. A run that answers more than once lists each response oldest first, separated by `---- Later result ----`. A substantive report may precede a short later acknowledgement; report the substantive outcome.
17
17
 
18
18
  {{#openclaw}}
19
19
  ## How it runs
@@ -181,12 +181,12 @@ Don't reconstruct what happened: no re-running the agent, no `git` archaeology t
181
181
  {{#openclaw}}
182
182
  The current coding agent is `{{AGENT}}`, profile `{{PROFILE}}`. The profile's nonempty `models` replaces its displayed allowlist. Codex aliases `astra`, `sol`, `terra`, and `luna` resolve to the newest bundled matching slug only when selected; a configured full slug passes through unchanged.
183
183
 
184
- `{{ALIGNDEV}} code status` checks that a `running` process still owns its recorded pid. A dead run is sealed as `status: failed`, `exitReason: terminated` before the command reports it. `{{ALIGNDEV}} code quota` works without a `.plans` directory and does not start a coding session. Its output belongs to the selected native quota CLI's account; account pairing with the coding child is not verified.
184
+ `{{ALIGNDEV}} code status` seals a `running` record only when its `machineId` matches this installation and its pid is conclusively gone or reused. Foreign, legacy and uncertain records stay `running`; a sealed run reports `status: failed`, `exitReason: terminated`. `{{ALIGNDEV}} code quota` works without a `.plans` directory and does not start a coding session. Its output belongs to the selected native quota CLI's account; account pairing with the coding child is not verified.
185
185
  {{/openclaw}}
186
186
  {{#codingAgent}}
187
187
  The current coding agent is `{{AGENT}}`, profile `{{PROFILE}}`. A nonempty profile `models` list replaces its accepted model list. Pi has no finite allowlist by default: native selectors pass through unchanged, preferably `provider/model`, with optional thinking suffix. For a Pi child without `--model`, a new run uses profile `defaultModel`, else Pi's own default; a resume retains and validates its recorded model. Codex aliases `astra`, `sol`, `terra`, and `luna` resolve to the newest bundled matching slug only when selected; a configured full slug passes through unchanged.
188
188
 
189
- `{{ALIGNDEV}} code status` checks that a `running` process still owns its recorded pid. A dead run is sealed as `status: failed`, `exitReason: terminated` before the command reports it. `{{ALIGNDEV}} code quota` needs no `.plans` and starts no session. Its output belongs to the selected native quota CLI's account; account pairing with the coding child is not verified.
189
+ `{{ALIGNDEV}} code status` seals a `running` record only when its `machineId` matches this installation and its pid is conclusively gone or reused. Foreign, legacy and uncertain records stay `running`; a sealed run reports `status: failed`, `exitReason: terminated`. `{{ALIGNDEV}} code quota` needs no `.plans` and starts no session. Its output belongs to the selected native quota CLI's account; account pairing with the coding child is not verified.
190
190
  {{/codingAgent}}
191
191
 
192
192
  ### Profiles and resume
@@ -61,7 +61,7 @@ On approval:
61
61
  1. Complete `{{ALIGNDEV}} guide work-files-setup` under the approved preparation, then run `{{ALIGNFIRST}} sync`. Run `{{ALIGNFIRST}} ticket --side` from PROJECT_PATH, write `{TICKET_DIR}A1-request.md` with the recorded request, then run `{{ALIGNFIRST}} sync`.
62
62
  2. Create `{TICKET_ID}/alignfirst-setup` in the main worktree. This setup branch is the second main-worktree exception, next to new-project bootstrap.
63
63
  3. Run `{{ALIGNDEV}} guide code`. From PROJECT_PATH, delegate the preparation to the agent without a protocol: use the `alignfirst-setup-guide` skill and prepare the repository for an assistant, with the user's work-files repository decision and its URL. It must run `{{ALIGNDEV}} project doctor` after writing `.alignfirst.json` and before workspace setup, stopping on an unhealthy inventory. Instruct the agent to commit and push the branch. The setup guide's rule against pushing addresses a human's laptop session, not this procedure.
64
- 4. Have the agent create a ready pull request, not a draft.
64
+ 4. Have the agent create a pull request.
65
65
  5. End the turn on the PR link and state that work resumes once the PR is merged.
66
66
 
67
67
  ### Step 5 — After the merge
@@ -486,10 +486,10 @@ Two triggers, both edited through the agent:
486
486
  - You learn something non-obvious about how to work in a project — a command, a quirk, a convention not yet written down. Propose capturing it in the project's `DEVELOPERS.md`, created at the repository root when the project has none, ask for confirmation, then have the agent make the edit.
487
487
  {{/codingAgent}}
488
488
  {{#openclaw}}
489
- - The user asks to retain a rule for the project. No confirmation needed: the rule goes into both `AGENTS.md` and `DEVELOPERS.md`. When the thread has an active ticket and the rule is simple, add it on the current branch, so the ticket's PR carries it. When the rule is complex or the thread has no ticket, reserve a side ticket (Step 5), set up a workspace on a new branch for the rule, and create a ready pull request.
489
+ - The user asks to retain a rule for the project. No confirmation needed: the rule goes into both `AGENTS.md` and `DEVELOPERS.md`. When the thread has an active ticket and the rule is simple, add it on the current branch, so the ticket's PR carries it. When the rule is complex or the thread has no ticket, reserve a side ticket (Step 5), set up a workspace on a new branch for the rule, and create a pull request.
490
490
  {{/openclaw}}
491
491
  {{#codingAgent}}
492
- - The user asks to retain a rule for the project. No confirmation needed: the rule goes into both `AGENTS.md` and `DEVELOPERS.md`. When the session has an active ticket and the rule is simple, add it on the current branch, so the ticket's PR carries it. When the rule is complex or the session has no ticket, reserve a side ticket (Step 5), set up a workspace on a new branch for the rule, and create a ready pull request.
492
+ - The user asks to retain a rule for the project. No confirmation needed: the rule goes into both `AGENTS.md` and `DEVELOPERS.md`. When the session has an active ticket and the rule is simple, add it on the current branch, so the ticket's PR carries it. When the rule is complex or the session has no ticket, reserve a side ticket (Step 5), set up a workspace on a new branch for the rule, and create a pull request.
493
493
  {{/codingAgent}}
494
494
 
495
495
  {{#openclaw}}
@@ -549,7 +549,7 @@ The author of a branch you reviewed pushes fixes and asks you to check them, or
549
549
 
550
550
  ### Merge/Pull requests
551
551
 
552
- You are the judge of when the ticket's scope is done — a ticket can span several coding sessions, so no single run completion decides it. When you judge it done, create the MR/PR without asking — as a **draft**, unless the user asked for a ready one. Mark it ready when the user says so.
552
+ You are the judge of when the ticket's scope is done — a ticket can span several coding sessions, so no single run completion decides it. When you judge it done, create the MR/PR without asking.
553
553
 
554
554
  Before creating it: the code compiles, lint and tests pass, and you exercised the change manually (see "Always test the work manually"). Then run the review workflow with its fix step (see "Code review" above) — automatic, part of creating any MR/PR.
555
555