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 +9 -8
- package/dist/code/code-cli.d.ts +2 -1
- package/dist/code/code-cli.js +54 -28
- package/dist/code/machine-id.d.ts +1 -0
- package/dist/code/machine-id.js +34 -0
- package/dist/code/session-file.d.ts +8 -3
- package/dist/code/session-file.js +48 -33
- package/package.json +1 -1
- package/templates/guide/code.md +3 -3
- package/templates/guide/playbook/project-lifecycle.md +1 -1
- package/templates/guide/playbook/working-session.md +3 -3
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.
|
|
16
|
-
2.
|
|
17
|
-
3.
|
|
18
|
-
4. Has
|
|
19
|
-
5. Has the
|
|
20
|
-
6.
|
|
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.
|
|
23
|
-
9. Has the
|
|
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
|
|
package/dist/code/code-cli.d.ts
CHANGED
|
@@ -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;
|
package/dist/code/code-cli.js
CHANGED
|
@@ -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
|
|
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
|
-
|
|
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
|
|
87
|
-
const
|
|
88
|
-
|
|
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,
|
|
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
|
|
163
|
+
const requestedPath = resolve(tree.cwd, input);
|
|
158
164
|
const sessionsDir = displayPath(tree.cwd, tree.sessionsDir);
|
|
159
|
-
if (!isSessionFilePath(tree.sessionsDir,
|
|
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,
|
|
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({
|
|
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,
|
|
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,
|
|
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,
|
|
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
|
-
|
|
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
|
-
|
|
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):
|
|
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
|
|
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}`}
|
|
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
|
|
47
|
-
// transcript intact until the
|
|
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" ||
|
|
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
|
|
107
|
-
if (frontmatter.pid === null
|
|
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 (
|
|
120
|
-
return
|
|
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
|
-
//
|
|
139
|
-
//
|
|
140
|
-
|
|
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
|
|
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
package/templates/guide/code.md
CHANGED
|
@@ -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
|
|
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`
|
|
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`
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|