aligndev 0.23.3 → 0.25.0

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.
Files changed (48) hide show
  1. package/README.md +74 -19
  2. package/dist/alignfirst-cli.d.ts +1 -0
  3. package/dist/alignfirst-cli.js +43 -1
  4. package/dist/cli.js +7 -14
  5. package/dist/code/claude-agent.d.ts +1 -1
  6. package/dist/code/claude-agent.js +25 -11
  7. package/dist/code/code-cli.d.ts +9 -4
  8. package/dist/code/code-cli.js +216 -84
  9. package/dist/code/codex-agent.d.ts +2 -2
  10. package/dist/code/codex-agent.js +24 -8
  11. package/dist/code/codex-rollout.d.ts +1 -1
  12. package/dist/code/codex-rollout.js +9 -5
  13. package/dist/code/coding-agent.d.ts +1 -1
  14. package/dist/code/coding-agent.js +13 -4
  15. package/dist/code/models.d.ts +2 -2
  16. package/dist/code/models.js +27 -15
  17. package/dist/code/native-context.d.ts +2 -0
  18. package/dist/code/native-context.js +21 -0
  19. package/dist/code/pi-agent.d.ts +2 -0
  20. package/dist/code/pi-agent.js +240 -0
  21. package/dist/code/quota-process.d.ts +9 -0
  22. package/dist/code/quota-process.js +165 -0
  23. package/dist/code/quota.d.ts +2 -3
  24. package/dist/code/quota.js +92 -98
  25. package/dist/code/run-agent.d.ts +12 -3
  26. package/dist/code/run-agent.js +48 -19
  27. package/dist/code/session-file.d.ts +3 -0
  28. package/dist/code/session-file.js +33 -10
  29. package/dist/config.d.ts +44 -7
  30. package/dist/config.js +163 -36
  31. package/dist/guide/code-guide.d.ts +2 -2
  32. package/dist/guide/code-guide.js +17 -6
  33. package/dist/guide/guide-cli.js +16 -7
  34. package/dist/json-shape.d.ts +3 -0
  35. package/dist/json-shape.js +23 -0
  36. package/dist/package-version.d.ts +1 -0
  37. package/dist/package-version.js +7 -0
  38. package/dist/project/layout.d.ts +4 -0
  39. package/dist/project/layout.js +28 -10
  40. package/dist/project/render.js +3 -1
  41. package/dist/project/status.d.ts +2 -1
  42. package/dist/project/status.js +1 -0
  43. package/package.json +1 -1
  44. package/templates/guide/code.md +102 -21
  45. package/templates/guide/playbook/consultation.md +5 -0
  46. package/templates/guide/playbook/playbook.md +12 -2
  47. package/templates/guide/playbook/project-workspace-setup.md +1 -1
  48. package/templates/guide/playbook/working-session.md +10 -0
@@ -2,14 +2,15 @@ import { existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
2
2
  import { extname, isAbsolute, join, relative, resolve, sep } from "node:path";
3
3
  import { parseArgs } from "node:util";
4
4
  import { loadCatchup, loadContext, openTicket, reserveSideTicket } from "../alignfirst-cli.js";
5
- import { resolveCodeConfig } from "../config.js";
5
+ import { resolveCodeConfig, resolveQuotaConfig, } from "../config.js";
6
6
  import { errorMessage } from "../errors.js";
7
7
  import { companionInUse, readProjectReport, } from "../project/layout.js";
8
8
  import { createAgentAdapter } from "./coding-agent.js";
9
- import { resolveModels } from "./models.js";
9
+ import { expandModelAlias, resolveModels } from "./models.js";
10
+ import { describeNativeStorage } from "./native-context.js";
10
11
  import { buildPrompt, PROTOCOLS } from "./prompt.js";
11
- import { buildAgentEnv, runAgent } from "./run-agent.js";
12
- import { applyCompletion, findNewestSessionFile, listSessionRecords, readPidStartTime, reconcileSessionFile, resolveSessionFilePath, writeInitialSessionFile, } from "./session-file.js";
12
+ import { runAgent } from "./run-agent.js";
13
+ import { applyCompletion, createSessionFile, findNewestSessionFile, listSessionRecords, readPidStartTime, reconcileSessionFile, RESULT_MARKER, } from "./session-file.js";
13
14
  // Distinct from 1 (ordinary run failure) so a script can branch on an auth failure that needs an
14
15
  // operator re-login rather than a retry.
15
16
  const EXIT_AUTH_REQUIRED = 2;
@@ -20,7 +21,9 @@ const SESSION_OPTIONS = {
20
21
  ticket: { type: "string" },
21
22
  message: { type: "string", short: "m" },
22
23
  model: { type: "string" },
24
+ profile: { type: "string" },
23
25
  meta: { type: "string" },
26
+ quiet: { type: "boolean" },
24
27
  help: { type: "boolean", short: "h", default: false },
25
28
  };
26
29
  // Items the agent would not find in the repository: a new session gets `alignfirst context`.
@@ -32,17 +35,35 @@ const CONTEXT_COMPANION_ITEMS = [
32
35
  ];
33
36
  const TICKET_PATH_ERROR = "Error: --ticket must be a single path segment " +
34
37
  "(letters, digits, '.', '-', '_'); no path separators or '..'.";
35
- export async function runCode(tokens, config, ctx) {
38
+ export async function runCode(tokens, loadSettings, ctx) {
36
39
  try {
37
40
  const command = parseCodeArgs(tokens, ctx.forms.aligndev);
38
41
  if (command.kind === "status")
39
- return showStatus(ctx, command.target);
40
- const code = resolveCodeConfig(config, ctx.env);
42
+ return showStatus(ctx, command.target, command.includeResult);
43
+ if (command.kind === "help" && command.status === true) {
44
+ ctx.stdout.write(`${ctx.forms.aligndev} code status (<session-file> | --ticket <id> | --no-ticket | --meta <key>) [--result]\nRead durable metadata without reading settings.\n`);
45
+ return 0;
46
+ }
47
+ const config = loadSettings();
48
+ const report = readReport(ctx);
49
+ const records = command.kind === "session" ? listSessionRecords(report.locations._aligndev.path) : [];
50
+ const args = command.kind === "session" ? command.args : undefined;
51
+ const previous = args?.resume === undefined
52
+ ? undefined
53
+ : latestRecord(records.filter((record) => record.frontmatter.sessionId === args.resume));
54
+ if (args?.resume !== undefined && previous === undefined) {
55
+ throw new Error(unknownResumeError(args.resume, records));
56
+ }
57
+ const code = resolveCodeConfig(config, ctx.env, {
58
+ project: report.aligndev,
59
+ explicit: args?.profile ?? (command.kind === "session" ? undefined : command.profile),
60
+ recorded: previous?.frontmatter.profile,
61
+ });
41
62
  if (command.kind === "quota")
42
63
  return await showQuota(ctx, code);
43
- const models = resolveModels(code.agent, code.models);
64
+ const models = resolveModels(code.agent, code.models, code.modelAliases);
44
65
  if (command.kind === "help") {
45
- ctx.stdout.write(renderHelp(code.agent, models, ctx.forms));
66
+ ctx.stdout.write(renderHelp(code, models, ctx.forms));
46
67
  return 0;
47
68
  }
48
69
  loadMessage(command.args, ctx.cwd);
@@ -51,18 +72,23 @@ export async function runCode(tokens, config, ctx) {
51
72
  ctx.stderr.write(`${validationError}\n`);
52
73
  return 1;
53
74
  }
54
- return await runSession(command.args, code, ctx);
75
+ return await runSession(command.args, code, ctx, report, records, previous);
55
76
  }
56
77
  catch (error) {
57
78
  ctx.stderr.write(`${errorMessage(error)}\n`);
58
79
  return 1;
59
80
  }
60
81
  }
61
- function showStatus(ctx, target) {
82
+ function showStatus(ctx, target, includeResult) {
62
83
  const tree = sessionTreeOf(readReport(ctx), ctx.cwd);
63
84
  const sessionFilePath = resolveStatusTargetSessionFile(tree, target);
64
85
  const completion = reconcileSessionFile(sessionFilePath);
65
86
  ctx.stdout.write(renderSessionStatus(tree.cwd, sessionFilePath, completion.frontmatter));
87
+ if (includeResult &&
88
+ completion.frontmatter.status !== "running" &&
89
+ completion.result !== undefined) {
90
+ ctx.stdout.write(`${RESULT_MARKER}\n${completion.result}\n`);
91
+ }
66
92
  return 0;
67
93
  }
68
94
  function readReport(ctx) {
@@ -78,12 +104,21 @@ function sessionTreeOf(report, cwd) {
78
104
  };
79
105
  }
80
106
  async function showQuota(ctx, code) {
81
- const report = await ctx.quotaReader(code.agent, {
82
- cwd: ctx.cwd,
83
- env: ctx.env,
84
- unset: code.unset,
85
- });
86
- ctx.stdout.write(`${report.trimEnd()}\n`);
107
+ const label = `profile ${JSON.stringify(code.profile ?? "(built-in)")}`;
108
+ const quota = resolveQuotaConfig(code, ctx.env);
109
+ if (quota.source === "none")
110
+ throw new Error(`Quota is disabled for ${label} (quota.source: none).`);
111
+ let report;
112
+ try {
113
+ report = await ctx.quotaReader(quota.source, { cwd: ctx.cwd, env: quota.env });
114
+ }
115
+ catch (error) {
116
+ throw new Error(`Quota source ${quota.source}, ${label}, selected native configuration: ${errorMessage(error)} ` +
117
+ `Check that ${quota.source} is installed and authenticated under this quota configuration.`);
118
+ }
119
+ ctx.stdout.write(`Profile: ${code.profile ?? "(built-in)"}; native source: ${quota.source}\n` +
120
+ "Limits belong to this native CLI's account; account pairing with the coding agent is not verified.\n" +
121
+ `${report.trimEnd()}\n`);
87
122
  return 0;
88
123
  }
89
124
  function resolveStatusTargetSessionFile(tree, target) {
@@ -155,6 +190,9 @@ function renderSessionStatus(cwd, sessionFilePath, frontmatter) {
155
190
  return [
156
191
  `sessionFile: ${displayPath(cwd, sessionFilePath)}`,
157
192
  `sessionId: ${frontmatter.sessionId ?? ""}`,
193
+ `agent: ${frontmatter.agent ?? ""}`,
194
+ `profile: ${frontmatter.profile ?? ""}`,
195
+ `model: ${frontmatter.model ?? ""}`,
158
196
  `status: ${frontmatter.status}`,
159
197
  `pid: ${frontmatter.pid ?? ""}`,
160
198
  `startedAt: ${frontmatter.startedAt}`,
@@ -174,7 +212,9 @@ export function parseCodeArgs(tokens, aligndev) {
174
212
  throw new Error(`Error: no command given. Run \`${aligndev} code --help\`.`);
175
213
  case "--help":
176
214
  case "-h":
177
- return { kind: "help" };
215
+ return parseBareCommand(tokens, "help");
216
+ case "--profile":
217
+ return parseBareCommand(tokens, "help");
178
218
  case "new":
179
219
  return parseNewCommand(rest);
180
220
  case "resume":
@@ -194,13 +234,14 @@ function parseStatusCommand(tokens) {
194
234
  ticket: { type: "string" },
195
235
  "no-ticket": { type: "boolean", default: false },
196
236
  meta: { type: "string" },
237
+ result: { type: "boolean", default: false },
197
238
  help: { type: "boolean", short: "h", default: false },
198
239
  },
199
240
  strict: true,
200
241
  allowPositionals: true,
201
242
  });
202
243
  if (values.help)
203
- return { kind: "help" };
244
+ return { kind: "help", status: true };
204
245
  const targetCount = positionals.length +
205
246
  Number(values.ticket !== undefined) +
206
247
  Number(values["no-ticket"]) +
@@ -209,16 +250,17 @@ function parseStatusCommand(tokens) {
209
250
  throw new Error("Error: `aligndev code status` takes exactly one of <session-file>, --ticket <id>, --no-ticket " +
210
251
  "or --meta <key>.");
211
252
  }
253
+ const includeResult = values.result;
212
254
  if (values.meta !== undefined)
213
- return { kind: "status", target: { kind: "meta", meta: values.meta } };
255
+ return { kind: "status", target: { kind: "meta", meta: values.meta }, includeResult };
214
256
  if (values.ticket !== undefined) {
215
257
  if (!isPathSafeTicket(values.ticket))
216
258
  throw new Error(TICKET_PATH_ERROR);
217
- return { kind: "status", target: { kind: "ticket", ticket: values.ticket } };
259
+ return { kind: "status", target: { kind: "ticket", ticket: values.ticket }, includeResult };
218
260
  }
219
261
  if (values["no-ticket"])
220
- return { kind: "status", target: { kind: "noTicket" } };
221
- return { kind: "status", target: { kind: "file", sessionFile: positionals[0] } };
262
+ return { kind: "status", target: { kind: "noTicket" }, includeResult };
263
+ return { kind: "status", target: { kind: "file", sessionFile: positionals[0] }, includeResult };
222
264
  }
223
265
  function parseNewCommand(tokens) {
224
266
  const { values } = parseArgs({
@@ -227,12 +269,14 @@ function parseNewCommand(tokens) {
227
269
  strict: true,
228
270
  });
229
271
  if (values.help)
230
- return { kind: "help" };
272
+ return { kind: "help", ...(values.profile === undefined ? {} : { profile: values.profile }) };
231
273
  return {
232
274
  kind: "session",
233
275
  args: {
276
+ profile: values.profile,
234
277
  ticket: values.ticket,
235
278
  noTicket: values["no-ticket"],
279
+ quiet: values.quiet,
236
280
  protocol: values.protocol,
237
281
  catchup: values.catchup,
238
282
  messageFile: values["message-file"],
@@ -250,7 +294,7 @@ function parseResumeCommand(tokens) {
250
294
  allowPositionals: true,
251
295
  });
252
296
  if (values.help)
253
- return { kind: "help" };
297
+ return { kind: "help", ...(values.profile === undefined ? {} : { profile: values.profile }) };
254
298
  if (positionals.length !== 1) {
255
299
  throw new Error("Error: `aligndev code resume` takes exactly one <sessionId>.");
256
300
  }
@@ -258,8 +302,10 @@ function parseResumeCommand(tokens) {
258
302
  kind: "session",
259
303
  args: {
260
304
  resume: positionals[0],
305
+ profile: values.profile,
261
306
  ticket: values.ticket,
262
307
  noTicket: false,
308
+ quiet: values.quiet,
263
309
  protocol: values.protocol,
264
310
  catchup: values.catchup,
265
311
  messageFile: values["message-file"],
@@ -272,10 +318,16 @@ function parseResumeCommand(tokens) {
272
318
  function parseBareCommand(tokens, kind) {
273
319
  const { values } = parseArgs({
274
320
  args: tokens,
275
- options: { help: { type: "boolean", short: "h", default: false } },
321
+ options: {
322
+ help: { type: "boolean", short: "h", default: false },
323
+ profile: { type: "string" },
324
+ },
276
325
  strict: true,
277
326
  });
278
- return values.help ? { kind: "help" } : { kind };
327
+ return {
328
+ kind: values.help ? "help" : kind,
329
+ ...(values.profile === undefined ? {} : { profile: values.profile }),
330
+ };
279
331
  }
280
332
  export function validateSessionArgs(args, models) {
281
333
  const isNew = args.resume === undefined;
@@ -283,8 +335,12 @@ export function validateSessionArgs(args, models) {
283
335
  if (args.protocol !== undefined && !PROTOCOLS.includes(args.protocol)) {
284
336
  return `Error: --protocol must be one of: ${PROTOCOLS.join(", ")}.`;
285
337
  }
286
- if (args.model !== undefined && !models.includes(args.model)) {
287
- return `Error: --model must be one of: ${models.join(", ")}.`;
338
+ if (args.model !== undefined) {
339
+ if (args.model.trim() === "")
340
+ return "Error: --model must be nonblank.";
341
+ if (models !== undefined && !models.includes(args.model)) {
342
+ return `Error: --model must be one of: ${models.join(", ")}.`;
343
+ }
288
344
  }
289
345
  if (args.protocol === undefined && !hasMessage && args.catchup !== true) {
290
346
  return "Error: --message is required when --protocol is not specified.";
@@ -320,10 +376,9 @@ function isPathSafeTicket(ticket) {
320
376
  // agent's background task) — aligndev owns no backgrounding or callback of its own. The per-run session
321
377
  // file is the durable result handoff: on completion the frontmatter carries the session id and
322
378
  // status, and the `---- Result ----` block carries the outcome for a waking caller (or a human).
323
- async function runSession(args, code, ctx) {
379
+ async function runSession(args, code, ctx, report, records, previous) {
324
380
  const { cwd, env, stdout, stderr, forms, alignfirstCommand, modelResolver } = ctx;
325
381
  const { agent } = code;
326
- const report = readReport(ctx);
327
382
  const tree = sessionTreeOf(report, cwd);
328
383
  const plans = report.locations[".plans"];
329
384
  if (!plans.exists) {
@@ -331,13 +386,18 @@ async function runSession(args, code, ctx) {
331
386
  `Create it, or run \`${forms.alignfirst} plans setup <clone>\`.\n`);
332
387
  return 1;
333
388
  }
334
- const records = listSessionRecords(tree.sessionsDir);
335
- const resolvedTicket = args.noTicket ? undefined : resolveTicket(args, records);
336
- const guardError = checkLaunchGuards(args, agent, tree.cwd, resolvedTicket, records);
389
+ const resolvedTicket = args.noTicket
390
+ ? undefined
391
+ : (args.ticket ??
392
+ (args.resume === undefined
393
+ ? inferTicketFromMessage(args.message ?? "")
394
+ : (previous?.frontmatter.ticket ?? undefined)));
395
+ const guardError = checkLaunchGuards(args, agent, tree.cwd, resolvedTicket, records, previous);
337
396
  if (guardError) {
338
397
  stderr.write(`${guardError}\n`);
339
398
  return 1;
340
399
  }
400
+ const model = selectModel(args, code, previous);
341
401
  const now = new Date();
342
402
  const ticket = args.noTicket ? reserveSideTicket(alignfirstCommand, cwd, env) : resolvedTicket;
343
403
  if (ticket !== undefined && !args.noTicket && args.resume === undefined) {
@@ -353,27 +413,29 @@ async function runSession(args, code, ctx) {
353
413
  const contextContent = args.resume === undefined && companionInUse(report, CONTEXT_COMPANION_ITEMS)
354
414
  ? loadContext(alignfirstCommand, cwd, env)
355
415
  : undefined;
356
- const model = selectModel(args, code, records);
357
- const sessionFilePath = resolveSessionFilePath(tree.sessionsDir, ticket, now);
358
- writeInitialSessionFile(sessionFilePath, buildFrontmatter({ args, agent, model, now, realCwd: tree.cwd, ticket }));
416
+ const sessionFilePath = createSessionFile(tree.sessionsDir, ticket, now, buildFrontmatter({ args, agent, profile: code.profile, model, now, realCwd: tree.cwd, ticket }));
359
417
  stdout.write(`Session file: ${displayPath(tree.cwd, sessionFilePath)}\n\n`);
360
418
  let executableModel;
361
419
  try {
362
- executableModel = await modelResolver(agent, model, {
420
+ executableModel = await modelResolver(agent, expandModelAlias(model, code.modelAliases), {
363
421
  cwd,
364
- env: buildAgentEnv(env, code.unset),
422
+ env: code.childEnv,
365
423
  });
366
424
  }
367
- catch (error) {
368
- const message = errorMessage(error);
425
+ catch {
426
+ const message = `Could not resolve the ${agent} model; check --model, profile.models/modelAliases and the agent installation. ` +
427
+ `${nativeContext(code)}.` +
428
+ (agent === "codex"
429
+ ? " For Codex aliases, update the Codex CLI or select an explicit full model slug."
430
+ : "");
369
431
  applyCompletion(sessionFilePath, {
370
432
  status: "failed",
371
433
  endedAt: new Date().toISOString(),
372
434
  exitReason: "error",
373
- sessionId: null,
435
+ sessionId: args.resume ?? null,
374
436
  result: message,
375
437
  });
376
- stderr.write(`${message}\n`);
438
+ writeFailureDiagnostic(ctx, sessionFilePath, message);
377
439
  return 1;
378
440
  }
379
441
  const runConfig = buildRunConfig({
@@ -383,27 +445,56 @@ async function runSession(args, code, ctx) {
383
445
  ticket,
384
446
  cwd,
385
447
  sessionFilePath,
386
- env,
387
448
  executableModel,
388
449
  catchupContent,
389
450
  contextContent,
390
451
  alignfirst: forms.alignfirst,
391
452
  });
392
- createMissingCompanion(report, runConfig.additionalDirectories);
453
+ createMissingCompanion(report);
393
454
  const result = await runAgent(runConfig, createAgentAdapter(agent), stdout);
394
455
  if (args.resume === undefined && result.sessionId) {
395
456
  stdout.write(`\nSession ID: ${result.sessionId}\n`);
396
457
  }
397
458
  if (result.authRequired) {
398
- stderr.write("aligndev code: coding agent not authenticated — an administrator must re-login on the host " +
399
- `${agent === "claude" ? "(`claude`, then `/login`)" : "(`codex login`)"}.\n`);
459
+ writeFailureDiagnostic(ctx, sessionFilePath, `${nativeContext(code)} not authenticated — an administrator must re-login ` +
460
+ "with the same effective environment as the child (apply profile unset/env/configDir, " +
461
+ "including HOME, PATH and credential routing), from the same working directory. " +
462
+ `Then use ${authenticationInstruction(agent)}. A bare login in another shell may use a different account.`);
400
463
  return EXIT_AUTH_REQUIRED;
401
464
  }
402
- return result.status === "succeeded" ? 0 : 1;
465
+ if (result.status === "succeeded")
466
+ return 0;
467
+ 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."}`);
468
+ return 1;
469
+ }
470
+ function nativeContext(code) {
471
+ return `${code.agent} profile ${JSON.stringify(code.profile ?? "(built-in)")} (${describeNativeStorage(code)})`;
472
+ }
473
+ function authenticationInstruction(agent) {
474
+ switch (agent) {
475
+ case "claude":
476
+ return "`claude`, then `/login`";
477
+ case "codex":
478
+ return "`codex login`";
479
+ case "pi":
480
+ return "`pi`, then `/login <provider>`, or configure provider credentials";
481
+ }
482
+ }
483
+ function writeFailureDiagnostic(ctx, sessionFilePath, message) {
484
+ ctx.stderr.write(`aligndev code: ${message}\nSession file: ${displayPath(ctx.cwd, sessionFilePath)}\n`);
485
+ }
486
+ // Keep arbitrary provider output (which may contain credentials) in the durable file.
487
+ function failureDiagnostic(agent, result) {
488
+ if (result.includes("ENOENT"))
489
+ return `${agent} could not start; check its installation and PATH.`;
490
+ if (result.includes("Could not send prompt:")) {
491
+ return `Could not send the prompt to ${agent}; inspect the session file before retrying.`;
492
+ }
493
+ return `${agent} run failed; inspect the session file for the failure details.`;
403
494
  }
404
495
  // Fail-fast launch guards, run against the (healed) session records before anything is written.
405
496
  // Returns the error to print, or `undefined` when the launch may proceed.
406
- export function checkLaunchGuards(args, agent, realCwd, ticket, records) {
497
+ export function checkLaunchGuards(args, agent, realCwd, ticket, records, previous) {
407
498
  if (args.resume !== undefined) {
408
499
  // A resumed run writes a new session file carrying the same sessionId as the original, so one
409
500
  // id can match several records — a running status on any of them blocks.
@@ -415,7 +506,7 @@ export function checkLaunchGuards(args, agent, realCwd, ticket, records) {
415
506
  return (`Error: session ${args.resume} is still running (pid ${running.frontmatter.pid}); ` +
416
507
  "wait for it to finish or kill it.");
417
508
  }
418
- const latest = latestRecord(matches);
509
+ const latest = previous ?? latestRecord(matches);
419
510
  if (latest.frontmatter.agent === null) {
420
511
  return (`Error: session ${args.resume} predates agent-aware sessions and cannot be resumed; ` +
421
512
  "start a new session.");
@@ -424,6 +515,10 @@ export function checkLaunchGuards(args, agent, realCwd, ticket, records) {
424
515
  return (`Error: session ${args.resume} belongs to agent ${latest.frontmatter.agent}, but the ` +
425
516
  `selected agent is ${agent}.`);
426
517
  }
518
+ if (agent === "pi" && !sameRealDirectory(latest.frontmatter.cwd, realCwd)) {
519
+ return (`Error: pi session ${args.resume} must resume from its recorded directory ` +
520
+ `${latest.frontmatter.cwd ?? "(missing; start a new session)"}.`);
521
+ }
427
522
  }
428
523
  // Protocol runs only, against other protocol runs: they share the working tree, and
429
524
  // `alignfirst ticket --next` reserves no work-file prefix within a ticket.
@@ -438,6 +533,16 @@ export function checkLaunchGuards(args, agent, realCwd, ticket, records) {
438
533
  }
439
534
  return;
440
535
  }
536
+ function sameRealDirectory(recorded, realCwd) {
537
+ if (recorded === null)
538
+ return false;
539
+ try {
540
+ return realpathSync(recorded) === realCwd;
541
+ }
542
+ catch {
543
+ return false;
544
+ }
545
+ }
441
546
  function busyProtocolError(record, scope) {
442
547
  return (`Error: a ${record.frontmatter.protocol} protocol run is already active ${scope} ` +
443
548
  `(${record.path}, pid ${record.frontmatter.pid}); one protocol run at a time per worktree ` +
@@ -474,7 +579,7 @@ export function resolveTicket(args, records) {
474
579
  // Latest record of the resumed session that carries a ticket — the resumed run keeps writing
475
580
  // under the same ticket directory, and its frontmatter keeps the ticket for later resumes.
476
581
  function inheritTicketFromResume(resume, records) {
477
- const ticketed = records.filter((r) => r.frontmatter.sessionId === resume && r.frontmatter.ticket !== null);
582
+ const ticketed = records.filter((r) => r.frontmatter.sessionId === resume);
478
583
  const latest = ticketed.sort((a, b) => b.frontmatter.startedAt.localeCompare(a.frontmatter.startedAt))[0];
479
584
  return latest?.frontmatter.ticket ?? undefined;
480
585
  }
@@ -491,26 +596,30 @@ function inferTicketFromMessage(message) {
491
596
  return;
492
597
  return [...candidates][0];
493
598
  }
494
- // `--model` wins. Otherwise a new session takes `code.defaultModel`, and a resume keeps the model
495
- // of its latest run, unchecked against the current allowlist. `undefined` leaves the agent's
496
- // default.
497
- function selectModel(args, code, records) {
599
+ // A null recorded model retains the native conversation's model; profile defaults are new-only.
600
+ function selectModel(args, code, previous) {
498
601
  if (args.model !== undefined)
499
602
  return args.model;
500
603
  if (args.resume === undefined)
501
604
  return code.defaultModel;
502
- const runs = records.filter((r) => r.frontmatter.sessionId === args.resume);
503
- return latestRecord(runs).frontmatter.model ?? undefined;
605
+ const model = previous?.frontmatter.model ?? undefined;
606
+ const models = resolveModels(code.agent, code.models, code.modelAliases);
607
+ if (model !== undefined &&
608
+ (model.trim() === "" || (models !== undefined && !models.includes(model)))) {
609
+ throw new Error("Error: retained session model is not accepted by the selected profile; supply --model with an accepted replacement.");
610
+ }
611
+ return model;
504
612
  }
505
613
  function buildFrontmatter(input) {
506
614
  const { args, now, ticket } = input;
507
615
  return {
508
616
  status: "running",
509
617
  agent: input.agent,
618
+ profile: input.profile,
510
619
  protocol: args.protocol ?? null,
511
620
  ticket: ticket ?? null,
512
621
  model: input.model ?? null,
513
- sessionId: null,
622
+ sessionId: args.resume ?? null,
514
623
  command: formatCommand(args),
515
624
  meta: args.meta ?? null,
516
625
  pid: process.pid,
@@ -540,6 +649,8 @@ function formatCommand(args) {
540
649
  parts.push("--catchup");
541
650
  if (args.model !== undefined)
542
651
  parts.push("--model", args.model);
652
+ if (args.profile !== undefined)
653
+ parts.push("--profile", JSON.stringify(args.profile));
543
654
  if (args.messageFile !== undefined) {
544
655
  parts.push("--message-file", JSON.stringify(args.messageFile));
545
656
  }
@@ -548,6 +659,8 @@ function formatCommand(args) {
548
659
  }
549
660
  if (args.meta !== undefined)
550
661
  parts.push("--meta", JSON.stringify(args.meta));
662
+ if (args.quiet === true)
663
+ parts.push("--quiet");
551
664
  return parts.join(" ");
552
665
  }
553
666
  export function buildRunConfig(input) {
@@ -563,31 +676,37 @@ export function buildRunConfig(input) {
563
676
  alignfirst: input.alignfirst,
564
677
  }),
565
678
  sessionFilePath: input.sessionFilePath,
679
+ nativeContext: nativeContext(code),
566
680
  cwd: input.cwd,
567
681
  resume: args.resume,
682
+ quiet: args.quiet,
568
683
  executableModel: input.executableModel,
569
684
  skipPermissions: code.skipPermissions,
570
- additionalDirectories: !code.skipPermissions && report.companion !== null ? [report.companion.dir] : [],
571
- unset: code.unset,
572
- env: input.env,
685
+ additionalDirectories: code.agent !== "pi" && !code.skipPermissions && report.companion !== null
686
+ ? [report.companion.dir]
687
+ : [],
688
+ env: code.childEnv,
573
689
  };
574
690
  }
575
691
  // A registered companion becomes writable before its directory exists: create it for the agent.
576
- function createMissingCompanion(report, additionalDirectories) {
692
+ function createMissingCompanion(report) {
577
693
  const { companion } = report;
578
- if (companion === null || companion.exists || !additionalDirectories.includes(companion.dir)) {
694
+ if (companion === null || companion.exists)
579
695
  return;
580
- }
581
696
  mkdirSync(companion.dir, { recursive: true });
582
697
  }
583
- function renderHelp(agent, models, forms) {
698
+ function renderHelp(code, models, forms) {
699
+ const { agent, profile, defaultModel } = code;
584
700
  const { aligndev, alignfirst } = forms;
585
- const permissionMode = agent === "claude"
586
- ? "--permission-mode auto (dangerous opt-out: --dangerously-skip-permissions)"
587
- : "--sandbox workspace-write (dangerous opt-out: --dangerously-bypass-approvals-and-sandbox)";
701
+ const permissionMode = agent === "pi"
702
+ ? "Ordinary OS permissions; profile.skipPermissions has no effect. Saved project trust is honored."
703
+ : agent === "claude"
704
+ ? "--permission-mode auto (dangerous opt-out: --dangerously-skip-permissions)"
705
+ : "--sandbox workspace-write (dangerous opt-out: --dangerously-bypass-approvals-and-sandbox)";
588
706
  const modelBehavior = agent === "codex"
589
707
  ? "Codex aliases astra, sol, terra, and luna resolve on demand; configured full slugs pass through."
590
- : "Claude model values pass through unchanged.";
708
+ : `${agent === "pi" ? "Pi native selectors (including provider/model:thinking)" : "Claude model values"} pass through unchanged.`;
709
+ const modelPolicy = models === undefined ? "Any nonblank pi-native selector" : `One of ${models.join(", ")}`;
591
710
  const requires = forms.viaNpx
592
711
  ? "Requires: the alignfirst CLI, run through npx, for the project layout, side tickets and the\ndelegated protocols."
593
712
  : "Requires: the alignfirst CLI on PATH (npm install -g alignfirst), for the project layout, side\ntickets and the delegated protocols.";
@@ -598,7 +717,7 @@ Usage:
598
717
  ${aligndev} code new --catchup --ticket <id> [--protocol <protocol>] [--message-file <path|->]
599
718
  ${aligndev} code new --message "..."
600
719
  ${aligndev} code resume <sessionId> [--protocol <protocol>] [--message "..."]
601
- ${aligndev} code status (<session-file> | --ticket <id> | --no-ticket | --meta <key>)
720
+ ${aligndev} code status (<session-file> | --ticket <id> | --no-ticket | --meta <key>) [--result]
602
721
  ${aligndev} code quota
603
722
  ${aligndev} code -h, --help
604
723
 
@@ -609,14 +728,18 @@ Commands:
609
728
  run of the ticket, of no-ticket work, or of the --meta key. Includes
610
729
  contextTokens, the context-window occupancy the run ended on, and
611
730
  contextCompacted. Does not start an agent.
612
- quota Show the selected coding agent's account limits and reset times.
731
+ quota Show native account limits via the profile's quota source.
613
732
 
614
733
  Options (status):
615
734
  --ticket <id> Newest run of that ticket.
616
735
  --no-ticket Newest run of no-ticket work.
617
736
  --meta <key> Newest run tagged with \`--meta <key>\`, wherever it sits.
737
+ --result Append the terminal run's final Result block, when present, without the
738
+ transcript. Running sessions show status only; default is metadata only.
618
739
 
619
740
  Options (new, resume):
741
+ --quiet Suppress the live transcript on stdout; keep all durable session output,
742
+ the initial Session file line, new Session ID, and failure diagnostics.
620
743
  --protocol <p> One of: ${PROTOCOLS.join(", ")}.
621
744
  --ticket <id> Ticket ID. \`new --protocol\` requires it or a side ticket through
622
745
  --no-ticket.
@@ -626,8 +749,8 @@ Options (new, resume):
626
749
  --catchup Load the ticket history before the message. new only.
627
750
  -m, --message "..." Message to send. Required for spec/aad, or without protocol/catchup.
628
751
  --message-file <path> Read the message from a UTF-8 file, or stdin with -. Exclusive with -m.
629
- --model <model> One of ${models.join(", ")}. A new session defaults to
630
- code.defaultModel, else to the coding agent's default. A resume keeps the
752
+ --model <model> ${modelPolicy}. A new session defaults to
753
+ profile.defaultModel, else to the coding agent's default. A resume keeps the
631
754
  session's model.
632
755
  --meta "..." Opaque handoff string, stored verbatim in the session file frontmatter
633
756
  (\`meta:\`). aligndev never interprets it; a later reader of the session file
@@ -636,21 +759,30 @@ Options (new, resume):
636
759
  ${requires}
637
760
 
638
761
  Config (~/.alignfirst/aligndev.settings.json):
639
- code.agent Coding agent: claude or codex (selected: ${agent}). Defaults to the coding
640
- agent that runs aligndev.
641
- code.defaultModel Default model of a new session, one of the models accepted by --model.
642
- code.models List replacing the models accepted by --model.
643
- code.skipPermissions true to run the coding agent with permission prompts disabled.
644
- code.unset Env vars to strip from the coding agent child.
762
+ code.profile Global named profile. Effective profile: ${profile ?? "(built-in)"} (selected: ${agent}).
763
+ code.defaultProfiles Per detected-agent default profile names.
764
+ code.profiles Complete named profiles: agent, configDir, env, unset, defaultModel,
765
+ models, modelAliases, skipPermissions, quota. No inheritance.
766
+ --profile <name> Override for new, resume, quota and help (also guide code).
767
+ Precedence: explicit > project > recorded resume > global > detected default.
768
+ Model default ${defaultModel ?? "native default"} (new only). Resume retains and validates its model.
769
+ One configured alias expands before native model handling.
770
+
771
+ Native configuration: ${describeNativeStorage(code)}.
772
+ Login must use the same effective environment as the child: apply profile unset/env/configDir,
773
+ including HOME, PATH and credential routing, from the same working directory. Then use
774
+ ${authenticationInstruction(agent)}. A bare login in another shell may use a different account.
775
+ Environment values are omitted.
645
776
 
646
777
  Selected-agent permissions: ${permissionMode}
647
- The normal mode also makes the project's companion directory writable.
778
+ The project's companion directory is prepared before launch; pi uses ordinary OS access.
648
779
  ${modelBehavior}
649
780
 
650
- ${aligndev} code runs a coding agent in the foreground and blocks until it finishes, streaming the
651
- transcript to stdout and to a session file under .plans/ or its companion. Coding runs can be
652
- very long: always run it as a background task. Your platform does the backgrounding; never
653
- detach it.
781
+ ${aligndev} code runs a coding agent in the foreground and blocks until it finishes. The transcript
782
+ is durable in a session file under .plans/ or its companion; stdout also streams it unless --quiet.
783
+ Coding runs can be very long. The host owns background execution and completion delivery;
784
+ verify its capability before launch, use --quiet, and never detach the command. On completion,
785
+ retrieve status --result with the exact session-file path or a unique per-run --meta key.
654
786
 
655
787
  Run \`${aligndev} guide code\` for the full delegation guide.
656
788
  `;
@@ -1,7 +1,7 @@
1
- import type { AgentAdapter, AgentProtocolState, RunConfig } from "./run-agent.js";
1
+ import { type AgentAdapter, type AgentProtocolState, type RunConfig } from "./run-agent.js";
2
2
  export declare function createCodexAdapter(): AgentAdapter;
3
3
  export declare function buildCodexArgs(config: RunConfig): string[];
4
- export declare function createCodexState(): AgentProtocolState;
4
+ export declare function createCodexState(config?: RunConfig): AgentProtocolState;
5
5
  export declare function interpretCodexLine(line: string, state: AgentProtocolState): string | undefined;
6
6
  export declare function assessCodexState(state: AgentProtocolState): {
7
7
  succeeded: boolean;