aligndev 0.23.3 → 0.24.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.
package/README.md CHANGED
@@ -26,17 +26,17 @@ A task can also start at any intermediate step.
26
26
 
27
27
  ## Two Ways to Run the Assistant
28
28
 
29
- **In your coding agent.** A Claude Code or Codex session becomes the assistant of the repository it starts in. You keep chatting in the same session; the agents it launches work in the background.
29
+ **In your coding agent.** A Claude Code, Codex or persistent Pi session becomes the assistant of the repository it starts in. You keep chatting in the same session; the agents it launches work in the background.
30
30
 
31
31
  **As an OpenClaw bot.** [AlignDev for OpenClaw](#start-as-an-openclaw-bot) deploys the assistant on a server, under its own name in Slack or Discord. It works on every project of the host, one thread per task.
32
32
 
33
- Either way, the agent is Claude Code or Codex. A coding-agent assistant launches its own kind by default.
33
+ For a coding-agent assistant, parent host and delegated child are independent: `code.agent` selects Claude Code, Codex or Pi. Without that setting, the detected parent kind is the default child. OpenClaw deployment templates still offer Claude Code or Codex.
34
34
 
35
- ## Start in Claude Code or Codex
35
+ ## Start in Claude Code, Codex or Pi
36
36
 
37
37
  The project needs an AlignFirst `.plans` directory, in its repository or in a [companion directory](https://github.com/paleo/alignfirst/tree/main/packages/alignfirst#companion-directories). The [setup guide](https://github.com/paleo/alignfirst/blob/main/skills/alignfirst-setup-guide/references/coding-agent-assistant.md) prepares it.
38
38
 
39
- The agent needs network access and writes outside the repository, so the assistant launches it outside its sandbox: approve that request when it comes.
39
+ The child needs network access and writes outside the repository. Claude Code/Codex parents request their established sandbox bypass or elevation; approve that request when it comes. Pi uses ordinary OS permissions and saved project trust. It has no implied sandbox or per-command approval boundary, and `code.skipPermissions` has no effect on Pi.
40
40
 
41
41
  ### With the Skill
42
42
 
@@ -46,11 +46,22 @@ Install the `aligndev` skill:
46
46
  npx skills add https://github.com/paleo/alignfirst --global --skill aligndev
47
47
  ```
48
48
 
49
- Then start a session in the project and invoke `/aligndev` in Claude Code, or `$aligndev` in Codex.
49
+ Then start a session in the project and invoke `/aligndev` in Claude Code, `$aligndev` in Codex, or `/skill:aligndev` in Pi. To target Pi explicitly, add `--agent pi` to the installer command. Pi discovers global `~/.agents/skills/`; verify the current installer's target/layout when upgrading.
50
+
51
+ ### Pi's Separate Tools
52
+
53
+ The skill supplies instructions, not executable tools. Install only the package needed by each role:
54
+
55
+ - **Persistent Pi parent assistant:** `pi install npm:@alignfirst/pi-background` supplies the generic `background` tool. The playbook uses it to launch ordinary `aligndev code new/resume ... --quiet --meta <unique-run-key>` commands. On completion it validates the job handle, then retrieves the exact durable run through `code status <file> --result` or its unique meta key. A one-shot Pi process exits after its answer and cannot serve this role.
56
+ - **Pi coding child or direct AlignFirst user:** `pi install npm:@alignfirst/pi-subagent` supplies synchronous isolated plan/review delegation. If parent and child are both Pi, their respective environments need both capabilities. Neither package installs the skill or the other package.
57
+
58
+ Before replacing a local extension that already registers `subagent`, obtain the user's approval and disable that extension explicitly with `pi config`. Keep existing profiles; do not overwrite them or load two implementations. Reload after installation; `/reload` cancels active jobs and subagents.
59
+
60
+ Background reporting uses Pi's native follow-up delivery. Manual compaction and cancelled/failed navigation may delay notices until another turn; interruption or queue clearing can lose automatic continuation. Submitted notices may appear after reload/navigation and must be checked for current ownership. There is no exactly-once or crash-recovery guarantee. Normal session shutdown cancels owned work. See the [extension architecture](https://github.com/paleo/alignfirst/blob/main/docs/pi-extensions.md) and each package README for limits.
50
61
 
51
62
  ### Without a Skill
52
63
 
53
- Add this section to your global agent instructions (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, or the equivalent):
64
+ Add this section to your global agent instructions (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.pi/agent/AGENTS.md`, or the equivalent):
54
65
 
55
66
  ```markdown
56
67
  ## AlignDev
@@ -63,7 +74,8 @@ Then ask your session to work with aligndev.
63
74
  ### Requirements
64
75
 
65
76
  - Node.js 22.11 or later. The assistant runs `aligndev` through `npx`, so there is nothing to install.
66
- - Claude Code or Codex installed and logged in: `claude` then `/login`, or `codex login`.
77
+ - The selected child installed and authenticated: `claude` then `/login`, `codex login`, or `pi` then `/login <provider>` (or configured provider credentials). Pi requires Node.js 22.19 or later; the Pi adapter and extensions target Pi 1.3.0.
78
+ - For Pi, select a usable native model, preferably `provider/model` (optional thinking suffix). Authenticate in the same account/configuration used by the child; never expose credential values in diagnostics.
67
79
  - Linux or macOS, or Windows through WSL.
68
80
 
69
81
  ## Configuration
@@ -78,13 +90,13 @@ Then ask your session to work with aligndev.
78
90
 
79
91
  - `platform` — `codingAgent` (default) for a coding-agent assistant, `openclaw` for an OpenClaw bot.
80
92
  - `projectsRoot` — the projects directory of an OpenClaw host. Required by `openclaw`. `~/` expands to the home directory; a relative path resolves against `~/.alignfirst/`.
81
- - `code.agent` — the agent: `claude` or `codex`. Default: the coding agent that runs the assistant, detected from its environment. Set it to launch the other one, or when both are detected, as with Codex in a VS Code terminal where the Claude Code extension is installed.
82
- - `code.defaultModel` — the model of a new session started without `--model`, one of `code.models`. Default: the agent's own default. A resumed session keeps its model.
83
- - `code.models` — the models the assistant may choose from. Default: Claude's `fable`, `opus`, `sonnet`, `haiku`, or Codex's `astra`, `sol`, `terra`, `luna`.
84
- - `code.skipPermissions` — `true` runs Claude Code with `--dangerously-skip-permissions` instead of `--permission-mode auto`, and Codex with `--dangerously-bypass-approvals-and-sandbox` instead of `--sandbox workspace-write`. Default: `false`.
93
+ - `code.agent` — the child: `claude`, `codex` or `pi`. Default: the coding agent running the assistant, detected from its environment. Set it to choose another child or resolve mixed host markers. It never selects the parent's launch tool.
94
+ - `code.defaultModel` — the model of a new session without `--model`, one of the accepted models. Default: the child's own default. A resumed session keeps its recorded model; Pi resumes require the original worktree.
95
+ - `code.models` — a nonempty list restricts accepted selectors. Defaults: Claude's `fable`, `opus`, `sonnet`, `haiku`, or Codex's `astra`, `sol`, `terra`, `luna`. Pi accepts any nonblank native selector by default, preferably `provider/model`; an absent or empty list adds no allowlist.
96
+ - `code.skipPermissions` — `true` runs Claude Code with `--dangerously-skip-permissions` instead of `--permission-mode auto`, and Codex with `--dangerously-bypass-approvals-and-sandbox` instead of `--sandbox workspace-write`. Default: `false`. Irrelevant to Pi's ordinary OS permissions.
85
97
  - `code.unset` — environment variables to hide from the agent, such as an API key meant for another tool on the host.
86
98
 
87
- Unknown keys and invalid values are errors.
99
+ Unknown keys and invalid values are errors. `aligndev code quota` is unsupported for Pi; consult the selected provider directly.
88
100
 
89
101
  ## Start as an OpenClaw Bot
90
102
 
@@ -22,6 +22,7 @@ export type CodeCommand = {
22
22
  } | {
23
23
  kind: "status";
24
24
  target: StatusTarget;
25
+ includeResult: boolean;
25
26
  } | {
26
27
  kind: "quota";
27
28
  } | {
@@ -50,10 +51,11 @@ export interface SessionArgs {
50
51
  message?: string;
51
52
  model?: string;
52
53
  meta?: string;
54
+ quiet?: boolean;
53
55
  }
54
56
  export declare function runCode(tokens: string[], config: LoadedConfig, ctx: CodeContext): Promise<number>;
55
57
  export declare function parseCodeArgs(tokens: string[], aligndev: string): CodeCommand;
56
- export declare function validateSessionArgs(args: SessionArgs, models: readonly string[]): string | undefined;
58
+ export declare function validateSessionArgs(args: SessionArgs, models: readonly string[] | undefined): string | undefined;
57
59
  export declare function checkLaunchGuards(args: SessionArgs, agent: CodingAgent, realCwd: string, ticket: string | undefined, records: SessionRecord[]): string | undefined;
58
60
  export declare function resolveTicket(args: SessionArgs, records: SessionRecord[]): string | undefined;
59
61
  export interface RunInput {
@@ -9,7 +9,7 @@ import { createAgentAdapter } from "./coding-agent.js";
9
9
  import { resolveModels } from "./models.js";
10
10
  import { buildPrompt, PROTOCOLS } from "./prompt.js";
11
11
  import { buildAgentEnv, runAgent } from "./run-agent.js";
12
- import { applyCompletion, findNewestSessionFile, listSessionRecords, readPidStartTime, reconcileSessionFile, resolveSessionFilePath, writeInitialSessionFile, } from "./session-file.js";
12
+ import { applyCompletion, findNewestSessionFile, listSessionRecords, readPidStartTime, reconcileSessionFile, resolveSessionFilePath, RESULT_MARKER, writeInitialSessionFile, } from "./session-file.js";
13
13
  // Distinct from 1 (ordinary run failure) so a script can branch on an auth failure that needs an
14
14
  // operator re-login rather than a retry.
15
15
  const EXIT_AUTH_REQUIRED = 2;
@@ -21,6 +21,7 @@ const SESSION_OPTIONS = {
21
21
  message: { type: "string", short: "m" },
22
22
  model: { type: "string" },
23
23
  meta: { type: "string" },
24
+ quiet: { type: "boolean" },
24
25
  help: { type: "boolean", short: "h", default: false },
25
26
  };
26
27
  // Items the agent would not find in the repository: a new session gets `alignfirst context`.
@@ -36,7 +37,7 @@ export async function runCode(tokens, config, ctx) {
36
37
  try {
37
38
  const command = parseCodeArgs(tokens, ctx.forms.aligndev);
38
39
  if (command.kind === "status")
39
- return showStatus(ctx, command.target);
40
+ return showStatus(ctx, command.target, command.includeResult);
40
41
  const code = resolveCodeConfig(config, ctx.env);
41
42
  if (command.kind === "quota")
42
43
  return await showQuota(ctx, code);
@@ -58,11 +59,16 @@ export async function runCode(tokens, config, ctx) {
58
59
  return 1;
59
60
  }
60
61
  }
61
- function showStatus(ctx, target) {
62
+ function showStatus(ctx, target, includeResult) {
62
63
  const tree = sessionTreeOf(readReport(ctx), ctx.cwd);
63
64
  const sessionFilePath = resolveStatusTargetSessionFile(tree, target);
64
65
  const completion = reconcileSessionFile(sessionFilePath);
65
66
  ctx.stdout.write(renderSessionStatus(tree.cwd, sessionFilePath, completion.frontmatter));
67
+ if (includeResult &&
68
+ completion.frontmatter.status !== "running" &&
69
+ completion.result !== undefined) {
70
+ ctx.stdout.write(`${RESULT_MARKER}\n${completion.result}\n`);
71
+ }
66
72
  return 0;
67
73
  }
68
74
  function readReport(ctx) {
@@ -194,6 +200,7 @@ function parseStatusCommand(tokens) {
194
200
  ticket: { type: "string" },
195
201
  "no-ticket": { type: "boolean", default: false },
196
202
  meta: { type: "string" },
203
+ result: { type: "boolean", default: false },
197
204
  help: { type: "boolean", short: "h", default: false },
198
205
  },
199
206
  strict: true,
@@ -209,16 +216,17 @@ function parseStatusCommand(tokens) {
209
216
  throw new Error("Error: `aligndev code status` takes exactly one of <session-file>, --ticket <id>, --no-ticket " +
210
217
  "or --meta <key>.");
211
218
  }
219
+ const includeResult = values.result;
212
220
  if (values.meta !== undefined)
213
- return { kind: "status", target: { kind: "meta", meta: values.meta } };
221
+ return { kind: "status", target: { kind: "meta", meta: values.meta }, includeResult };
214
222
  if (values.ticket !== undefined) {
215
223
  if (!isPathSafeTicket(values.ticket))
216
224
  throw new Error(TICKET_PATH_ERROR);
217
- return { kind: "status", target: { kind: "ticket", ticket: values.ticket } };
225
+ return { kind: "status", target: { kind: "ticket", ticket: values.ticket }, includeResult };
218
226
  }
219
227
  if (values["no-ticket"])
220
- return { kind: "status", target: { kind: "noTicket" } };
221
- return { kind: "status", target: { kind: "file", sessionFile: positionals[0] } };
228
+ return { kind: "status", target: { kind: "noTicket" }, includeResult };
229
+ return { kind: "status", target: { kind: "file", sessionFile: positionals[0] }, includeResult };
222
230
  }
223
231
  function parseNewCommand(tokens) {
224
232
  const { values } = parseArgs({
@@ -233,6 +241,7 @@ function parseNewCommand(tokens) {
233
241
  args: {
234
242
  ticket: values.ticket,
235
243
  noTicket: values["no-ticket"],
244
+ quiet: values.quiet,
236
245
  protocol: values.protocol,
237
246
  catchup: values.catchup,
238
247
  messageFile: values["message-file"],
@@ -260,6 +269,7 @@ function parseResumeCommand(tokens) {
260
269
  resume: positionals[0],
261
270
  ticket: values.ticket,
262
271
  noTicket: false,
272
+ quiet: values.quiet,
263
273
  protocol: values.protocol,
264
274
  catchup: values.catchup,
265
275
  messageFile: values["message-file"],
@@ -283,8 +293,12 @@ export function validateSessionArgs(args, models) {
283
293
  if (args.protocol !== undefined && !PROTOCOLS.includes(args.protocol)) {
284
294
  return `Error: --protocol must be one of: ${PROTOCOLS.join(", ")}.`;
285
295
  }
286
- if (args.model !== undefined && !models.includes(args.model)) {
287
- return `Error: --model must be one of: ${models.join(", ")}.`;
296
+ if (args.model !== undefined) {
297
+ if (args.model.trim() === "")
298
+ return "Error: --model must be nonblank.";
299
+ if (models !== undefined && !models.includes(args.model)) {
300
+ return `Error: --model must be one of: ${models.join(", ")}.`;
301
+ }
288
302
  }
289
303
  if (args.protocol === undefined && !hasMessage && args.catchup !== true) {
290
304
  return "Error: --message is required when --protocol is not specified.";
@@ -373,7 +387,9 @@ async function runSession(args, code, ctx) {
373
387
  sessionId: null,
374
388
  result: message,
375
389
  });
376
- stderr.write(`${message}\n`);
390
+ writeFailureDiagnostic(ctx, sessionFilePath, args.quiet === true
391
+ ? `Could not resolve the ${agent} model; check --model, code.models and the agent installation.`
392
+ : message);
377
393
  return 1;
378
394
  }
379
395
  const runConfig = buildRunConfig({
@@ -389,17 +405,42 @@ async function runSession(args, code, ctx) {
389
405
  contextContent,
390
406
  alignfirst: forms.alignfirst,
391
407
  });
392
- createMissingCompanion(report, runConfig.additionalDirectories);
408
+ createMissingCompanion(report);
393
409
  const result = await runAgent(runConfig, createAgentAdapter(agent), stdout);
394
410
  if (args.resume === undefined && result.sessionId) {
395
411
  stdout.write(`\nSession ID: ${result.sessionId}\n`);
396
412
  }
397
413
  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`);
414
+ writeFailureDiagnostic(ctx, sessionFilePath, "coding agent not authenticated — an administrator must re-login on the host " +
415
+ `(${authenticationInstruction(agent)}).`);
400
416
  return EXIT_AUTH_REQUIRED;
401
417
  }
402
- return result.status === "succeeded" ? 0 : 1;
418
+ if (result.status === "succeeded")
419
+ return 0;
420
+ writeFailureDiagnostic(ctx, sessionFilePath, failureDiagnostic(agent, result.result));
421
+ return 1;
422
+ }
423
+ function authenticationInstruction(agent) {
424
+ switch (agent) {
425
+ case "claude":
426
+ return "`claude`, then `/login`";
427
+ case "codex":
428
+ return "`codex login`";
429
+ case "pi":
430
+ return "`pi`, then `/login <provider>`, or configure provider credentials";
431
+ }
432
+ }
433
+ function writeFailureDiagnostic(ctx, sessionFilePath, message) {
434
+ ctx.stderr.write(`aligndev code: ${message}\nSession file: ${displayPath(ctx.cwd, sessionFilePath)}\n`);
435
+ }
436
+ // Keep arbitrary provider output (which may contain credentials) in the durable file.
437
+ function failureDiagnostic(agent, result) {
438
+ if (result.includes("ENOENT"))
439
+ return `${agent} could not start; check its installation and PATH.`;
440
+ if (result.includes("Could not send prompt:")) {
441
+ return `Could not send the prompt to ${agent}; inspect the session file before retrying.`;
442
+ }
443
+ return `${agent} run failed; inspect the session file for the failure details.`;
403
444
  }
404
445
  // Fail-fast launch guards, run against the (healed) session records before anything is written.
405
446
  // Returns the error to print, or `undefined` when the launch may proceed.
@@ -424,6 +465,10 @@ export function checkLaunchGuards(args, agent, realCwd, ticket, records) {
424
465
  return (`Error: session ${args.resume} belongs to agent ${latest.frontmatter.agent}, but the ` +
425
466
  `selected agent is ${agent}.`);
426
467
  }
468
+ if (agent === "pi" && !sameRealDirectory(latest.frontmatter.cwd, realCwd)) {
469
+ return (`Error: pi session ${args.resume} must resume from its recorded directory ` +
470
+ `${latest.frontmatter.cwd ?? "(missing; start a new session)"}.`);
471
+ }
427
472
  }
428
473
  // Protocol runs only, against other protocol runs: they share the working tree, and
429
474
  // `alignfirst ticket --next` reserves no work-file prefix within a ticket.
@@ -438,6 +483,16 @@ export function checkLaunchGuards(args, agent, realCwd, ticket, records) {
438
483
  }
439
484
  return;
440
485
  }
486
+ function sameRealDirectory(recorded, realCwd) {
487
+ if (recorded === null)
488
+ return false;
489
+ try {
490
+ return realpathSync(recorded) === realCwd;
491
+ }
492
+ catch {
493
+ return false;
494
+ }
495
+ }
441
496
  function busyProtocolError(record, scope) {
442
497
  return (`Error: a ${record.frontmatter.protocol} protocol run is already active ${scope} ` +
443
498
  `(${record.path}, pid ${record.frontmatter.pid}); one protocol run at a time per worktree ` +
@@ -548,6 +603,8 @@ function formatCommand(args) {
548
603
  }
549
604
  if (args.meta !== undefined)
550
605
  parts.push("--meta", JSON.stringify(args.meta));
606
+ if (args.quiet === true)
607
+ parts.push("--quiet");
551
608
  return parts.join(" ");
552
609
  }
553
610
  export function buildRunConfig(input) {
@@ -565,29 +622,34 @@ export function buildRunConfig(input) {
565
622
  sessionFilePath: input.sessionFilePath,
566
623
  cwd: input.cwd,
567
624
  resume: args.resume,
625
+ quiet: args.quiet,
568
626
  executableModel: input.executableModel,
569
627
  skipPermissions: code.skipPermissions,
570
- additionalDirectories: !code.skipPermissions && report.companion !== null ? [report.companion.dir] : [],
628
+ additionalDirectories: code.agent !== "pi" && !code.skipPermissions && report.companion !== null
629
+ ? [report.companion.dir]
630
+ : [],
571
631
  unset: code.unset,
572
632
  env: input.env,
573
633
  };
574
634
  }
575
635
  // A registered companion becomes writable before its directory exists: create it for the agent.
576
- function createMissingCompanion(report, additionalDirectories) {
636
+ function createMissingCompanion(report) {
577
637
  const { companion } = report;
578
- if (companion === null || companion.exists || !additionalDirectories.includes(companion.dir)) {
638
+ if (companion === null || companion.exists)
579
639
  return;
580
- }
581
640
  mkdirSync(companion.dir, { recursive: true });
582
641
  }
583
642
  function renderHelp(agent, models, forms) {
584
643
  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)";
644
+ const permissionMode = agent === "pi"
645
+ ? "Ordinary OS permissions; code.skipPermissions has no effect. Saved project trust is honored."
646
+ : agent === "claude"
647
+ ? "--permission-mode auto (dangerous opt-out: --dangerously-skip-permissions)"
648
+ : "--sandbox workspace-write (dangerous opt-out: --dangerously-bypass-approvals-and-sandbox)";
588
649
  const modelBehavior = agent === "codex"
589
650
  ? "Codex aliases astra, sol, terra, and luna resolve on demand; configured full slugs pass through."
590
- : "Claude model values pass through unchanged.";
651
+ : `${agent === "pi" ? "Pi native selectors (including provider/model:thinking)" : "Claude model values"} pass through unchanged.`;
652
+ const modelPolicy = models === undefined ? "Any nonblank pi-native selector" : `One of ${models.join(", ")}`;
591
653
  const requires = forms.viaNpx
592
654
  ? "Requires: the alignfirst CLI, run through npx, for the project layout, side tickets and the\ndelegated protocols."
593
655
  : "Requires: the alignfirst CLI on PATH (npm install -g alignfirst), for the project layout, side\ntickets and the delegated protocols.";
@@ -598,7 +660,7 @@ Usage:
598
660
  ${aligndev} code new --catchup --ticket <id> [--protocol <protocol>] [--message-file <path|->]
599
661
  ${aligndev} code new --message "..."
600
662
  ${aligndev} code resume <sessionId> [--protocol <protocol>] [--message "..."]
601
- ${aligndev} code status (<session-file> | --ticket <id> | --no-ticket | --meta <key>)
663
+ ${aligndev} code status (<session-file> | --ticket <id> | --no-ticket | --meta <key>) [--result]
602
664
  ${aligndev} code quota
603
665
  ${aligndev} code -h, --help
604
666
 
@@ -609,14 +671,18 @@ Commands:
609
671
  run of the ticket, of no-ticket work, or of the --meta key. Includes
610
672
  contextTokens, the context-window occupancy the run ended on, and
611
673
  contextCompacted. Does not start an agent.
612
- quota Show the selected coding agent's account limits and reset times.
674
+ quota Show account limits and reset times (unsupported for pi).
613
675
 
614
676
  Options (status):
615
677
  --ticket <id> Newest run of that ticket.
616
678
  --no-ticket Newest run of no-ticket work.
617
679
  --meta <key> Newest run tagged with \`--meta <key>\`, wherever it sits.
680
+ --result Append the terminal run's final Result block, when present, without the
681
+ transcript. Running sessions show status only; default is metadata only.
618
682
 
619
683
  Options (new, resume):
684
+ --quiet Suppress the live transcript on stdout; keep all durable session output,
685
+ the initial Session file line, new Session ID, and failure diagnostics.
620
686
  --protocol <p> One of: ${PROTOCOLS.join(", ")}.
621
687
  --ticket <id> Ticket ID. \`new --protocol\` requires it or a side ticket through
622
688
  --no-ticket.
@@ -626,7 +692,7 @@ Options (new, resume):
626
692
  --catchup Load the ticket history before the message. new only.
627
693
  -m, --message "..." Message to send. Required for spec/aad, or without protocol/catchup.
628
694
  --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
695
+ --model <model> ${modelPolicy}. A new session defaults to
630
696
  code.defaultModel, else to the coding agent's default. A resume keeps the
631
697
  session's model.
632
698
  --meta "..." Opaque handoff string, stored verbatim in the session file frontmatter
@@ -636,7 +702,7 @@ Options (new, resume):
636
702
  ${requires}
637
703
 
638
704
  Config (~/.alignfirst/aligndev.settings.json):
639
- code.agent Coding agent: claude or codex (selected: ${agent}). Defaults to the coding
705
+ code.agent Coding agent: claude, codex or pi (selected: ${agent}). Defaults to the coding
640
706
  agent that runs aligndev.
641
707
  code.defaultModel Default model of a new session, one of the models accepted by --model.
642
708
  code.models List replacing the models accepted by --model.
@@ -644,13 +710,14 @@ Config (~/.alignfirst/aligndev.settings.json):
644
710
  code.unset Env vars to strip from the coding agent child.
645
711
 
646
712
  Selected-agent permissions: ${permissionMode}
647
- The normal mode also makes the project's companion directory writable.
713
+ The project's companion directory is prepared before launch; pi uses ordinary OS access.
648
714
  ${modelBehavior}
649
715
 
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.
716
+ ${aligndev} code runs a coding agent in the foreground and blocks until it finishes. The transcript
717
+ is durable in a session file under .plans/ or its companion; stdout also streams it unless --quiet.
718
+ Coding runs can be very long. The host owns background execution and completion delivery;
719
+ verify its capability before launch, use --quiet, and never detach the command. On completion,
720
+ retrieve status --result with the exact session-file path or a unique per-run --meta key.
654
721
 
655
722
  Run \`${aligndev} guide code\` for the full delegation guide.
656
723
  `;
@@ -1,5 +1,5 @@
1
1
  import type { AgentAdapter } from "./run-agent.js";
2
- export declare const CODING_AGENTS: readonly ["claude", "codex"];
2
+ export declare const CODING_AGENTS: readonly ["claude", "codex", "pi"];
3
3
  export type CodingAgent = (typeof CODING_AGENTS)[number];
4
4
  export declare function createAgentAdapter(agent: CodingAgent): AgentAdapter;
5
5
  export declare function detectCodingAgents(env: NodeJS.ProcessEnv): CodingAgent[];
@@ -1,16 +1,25 @@
1
1
  import { createClaudeAdapter } from "./claude-agent.js";
2
2
  import { createCodexAdapter } from "./codex-agent.js";
3
- export const CODING_AGENTS = ["claude", "codex"];
3
+ import { createPiAdapter } from "./pi-agent.js";
4
+ export const CODING_AGENTS = ["claude", "codex", "pi"];
4
5
  export function createAgentAdapter(agent) {
5
- return agent === "claude" ? createClaudeAdapter() : createCodexAdapter();
6
+ switch (agent) {
7
+ case "claude":
8
+ return createClaudeAdapter();
9
+ case "codex":
10
+ return createCodexAdapter();
11
+ case "pi":
12
+ return createPiAdapter();
13
+ }
6
14
  }
7
- // Each coding agent marks the commands it runs: Claude Code sets `CLAUDECODE=1` (documented), and
8
- // Codex sets `CODEX_THREAD_ID`.
15
+ // Host markers select the child only when code.agent is absent.
9
16
  export function detectCodingAgents(env) {
10
17
  const detected = [];
11
18
  if (env.CLAUDECODE === "1")
12
19
  detected.push("claude");
13
20
  if (env.CODEX_THREAD_ID !== undefined && env.CODEX_THREAD_ID !== "")
14
21
  detected.push("codex");
22
+ if (env.PI_CODING_AGENT === "true" || env.AI_AGENT === "pi")
23
+ detected.push("pi");
15
24
  return detected;
16
25
  }
@@ -1,7 +1,7 @@
1
1
  import type { CodingAgent } from "./coding-agent.js";
2
2
  export declare const CLAUDE_DEFAULT_MODELS: readonly ["fable", "opus", "sonnet", "haiku"];
3
3
  export declare const CODEX_DEFAULT_MODELS: readonly ["astra", "sol", "terra", "luna"];
4
- export declare function resolveModels(agent: CodingAgent, override: readonly string[] | undefined): readonly string[];
4
+ export declare function resolveModels(agent: CodingAgent, override: readonly string[] | undefined): readonly string[] | undefined;
5
5
  export interface ModelDiscoveryContext {
6
6
  cwd: string;
7
7
  env: NodeJS.ProcessEnv;
@@ -8,14 +8,21 @@ const CODEX_CATALOG_TIMEOUT_MS = 30_000;
8
8
  export function resolveModels(agent, override) {
9
9
  if (override !== undefined && override.length > 0)
10
10
  return override;
11
- return agent === "claude" ? CLAUDE_DEFAULT_MODELS : CODEX_DEFAULT_MODELS;
11
+ switch (agent) {
12
+ case "claude":
13
+ return CLAUDE_DEFAULT_MODELS;
14
+ case "codex":
15
+ return CODEX_DEFAULT_MODELS;
16
+ case "pi":
17
+ return;
18
+ }
12
19
  }
13
20
  export function createExecutableModelResolver(runCatalog = runCodexModelCatalog) {
14
21
  let cachedSlugs;
15
22
  return async (agent, selectedModel, context) => {
16
23
  if (selectedModel === undefined)
17
24
  return;
18
- if (agent === "claude" || !CODEX_ALIASES.has(selectedModel))
25
+ if (agent !== "codex" || !CODEX_ALIASES.has(selectedModel))
19
26
  return selectedModel;
20
27
  try {
21
28
  cachedSlugs ??= parseBundledModelSlugs(await runCatalog(context));
@@ -0,0 +1,2 @@
1
+ import type { AgentAdapter } from "./run-agent.js";
2
+ export declare function createPiAdapter(): AgentAdapter;
@@ -0,0 +1,229 @@
1
+ const MISSING_USAGE = "Pi's latest assistant message did not report valid context usage.";
2
+ const STOP_REASONS = new Set([
3
+ "pending",
4
+ "stop",
5
+ "length",
6
+ "toolUse",
7
+ "error",
8
+ "aborted",
9
+ "deferred",
10
+ ]);
11
+ export function createPiAdapter() {
12
+ return {
13
+ executable: "pi",
14
+ buildArgs: buildPiArgs,
15
+ createState: createPiState,
16
+ interpretLine: interpretPiLine,
17
+ assess: assessPiState,
18
+ isAuthenticationError: isPiAuthenticationError,
19
+ authenticationMessage: piAuthenticationMessage,
20
+ failureMessage: piFailure,
21
+ };
22
+ }
23
+ function buildPiArgs(config) {
24
+ const args = ["--mode", "json"];
25
+ if (config.executableModel !== undefined)
26
+ args.push("--model", config.executableModel);
27
+ if (config.resume !== undefined)
28
+ args.push("--session", config.resume);
29
+ return args;
30
+ }
31
+ function createPiState(config) {
32
+ return {
33
+ expectedSessionId: config.resume,
34
+ headerSeen: false,
35
+ settledAborted: false,
36
+ protocolComplete: false,
37
+ protocolFailed: false,
38
+ authEvidence: false,
39
+ contextCompacted: false,
40
+ contextTokensError: MISSING_USAGE,
41
+ };
42
+ }
43
+ function interpretPiLine(line, state) {
44
+ let event;
45
+ try {
46
+ event = JSON.parse(line);
47
+ }
48
+ catch {
49
+ return invalidProtocol(state, "invalid JSON record");
50
+ }
51
+ if (!isRecord(event) || typeof event.type !== "string") {
52
+ return invalidProtocol(state, "expected an event object with a type");
53
+ }
54
+ if (!state.headerSeen && event.type !== "session") {
55
+ invalidProtocol(state, "missing initial session header");
56
+ }
57
+ switch (event.type) {
58
+ case "session":
59
+ return captureHeader(event, state);
60
+ case "agent_start":
61
+ case "turn_start":
62
+ state.stopReason = undefined;
63
+ state.result = undefined;
64
+ state.protocolComplete = false;
65
+ return;
66
+ case "auto_retry_start":
67
+ case "compaction_start":
68
+ state.protocolComplete = false;
69
+ return;
70
+ case "message_start":
71
+ state.protocolComplete = false;
72
+ if (isRecord(event.message) && event.message.role === "assistant") {
73
+ state.stopReason = undefined;
74
+ state.result = undefined;
75
+ captureUsage(undefined, state);
76
+ }
77
+ return;
78
+ case "message_end":
79
+ return captureMessage(event, state);
80
+ case "agent_settled":
81
+ if (typeof event.aborted !== "boolean") {
82
+ return invalidProtocol(state, "agent_settled requires an aborted boolean");
83
+ }
84
+ state.protocolComplete = true;
85
+ state.settledAborted = event.aborted;
86
+ return;
87
+ case "tool_execution_start":
88
+ case "tool_execution_end":
89
+ return renderTool(event);
90
+ case "compaction_end":
91
+ if (event.aborted === false && isRecord(event.result))
92
+ state.contextCompacted = true;
93
+ return;
94
+ case "auto_retry_end":
95
+ if (event.success === false && typeof event.finalError === "string") {
96
+ state.failure = event.finalError;
97
+ state.authEvidence = isPiAuthenticationError(event.finalError);
98
+ }
99
+ return;
100
+ default:
101
+ return;
102
+ }
103
+ }
104
+ function invalidProtocol(state, detail) {
105
+ state.protocolFailed = true;
106
+ state.failure = `Invalid pi JSON stream: ${detail}.`;
107
+ return `[error] ${state.failure}`;
108
+ }
109
+ function isRecord(value) {
110
+ return typeof value === "object" && value !== null && !Array.isArray(value);
111
+ }
112
+ function captureHeader(event, state) {
113
+ if (state.headerSeen ||
114
+ event.version !== 3 ||
115
+ typeof event.id !== "string" ||
116
+ !/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/i.test(event.id) ||
117
+ typeof event.cwd !== "string" ||
118
+ event.cwd.trim() === "" ||
119
+ typeof event.timestamp !== "string" ||
120
+ !Number.isFinite(Date.parse(event.timestamp))) {
121
+ return invalidProtocol(state, "invalid or unsupported session header (requires pi 1.3.0)");
122
+ }
123
+ state.headerSeen = true;
124
+ if (state.expectedSessionId !== undefined && event.id !== state.expectedSessionId) {
125
+ return invalidProtocol(state, `resumed session ID ${event.id} differs from ${state.expectedSessionId}`);
126
+ }
127
+ state.sessionId = event.id;
128
+ return `[init] session ${event.id}`;
129
+ }
130
+ function captureMessage(event, state) {
131
+ state.protocolComplete = false;
132
+ const message = event.message;
133
+ if (!isRecord(message) || typeof message.role !== "string") {
134
+ return invalidProtocol(state, "message_end requires a message with a role");
135
+ }
136
+ if (message.role !== "assistant")
137
+ return;
138
+ captureUsage(message.usage, state);
139
+ if (!Array.isArray(message.content) ||
140
+ typeof message.stopReason !== "string" ||
141
+ !STOP_REASONS.has(message.stopReason) ||
142
+ message.content.some((block) => !isRecord(block) ||
143
+ typeof block.type !== "string" ||
144
+ (block.type === "text" && typeof block.text !== "string"))) {
145
+ return invalidProtocol(state, "invalid assistant message_end content or stop reason");
146
+ }
147
+ state.stopReason = message.stopReason;
148
+ const text = message.content
149
+ .flatMap((block) => isRecord(block) && block.type === "text" && typeof block.text === "string"
150
+ ? [block.text]
151
+ : [])
152
+ .join("\n");
153
+ state.result = text.trim() === "" ? undefined : text;
154
+ // A malformed protocol remains fatal even if a later model response succeeds.
155
+ if (!state.protocolFailed) {
156
+ state.failure = typeof message.errorMessage === "string" ? message.errorMessage : undefined;
157
+ }
158
+ state.authEvidence =
159
+ (message.stopReason === "error" || message.stopReason === "aborted") &&
160
+ typeof message.errorMessage === "string" &&
161
+ isPiAuthenticationError(message.errorMessage);
162
+ return state.result ?? (state.failure === undefined ? undefined : `[error] ${state.failure}`);
163
+ }
164
+ function captureUsage(usage, state) {
165
+ state.contextTokens = undefined;
166
+ state.contextTokensError = MISSING_USAGE;
167
+ if (!isRecord(usage))
168
+ return;
169
+ let total = 0;
170
+ for (const key of ["input", "output", "cacheRead", "cacheWrite"]) {
171
+ const count = usage[key];
172
+ if (typeof count !== "number" || !Number.isSafeInteger(count) || count < 0)
173
+ return;
174
+ total += count;
175
+ }
176
+ if (!Number.isSafeInteger(total))
177
+ return;
178
+ state.contextTokens = total;
179
+ state.contextTokensError = undefined;
180
+ }
181
+ function renderTool(event) {
182
+ if (typeof event.toolName !== "string")
183
+ return;
184
+ const outcome = event.type === "tool_execution_start" ? "start" : event.isError === true ? "error" : "done";
185
+ return `[tool: ${event.toolName}] ${outcome}`;
186
+ }
187
+ function assessPiState(state) {
188
+ const succeeded = state.sessionId !== undefined &&
189
+ state.protocolComplete &&
190
+ !state.protocolFailed &&
191
+ !state.settledAborted &&
192
+ state.stopReason === "stop" &&
193
+ state.result !== undefined &&
194
+ state.failure === undefined;
195
+ return {
196
+ succeeded,
197
+ sessionId: state.sessionId,
198
+ result: state.result,
199
+ error: succeeded || (!state.headerSeen && !state.protocolFailed) ? undefined : piFailure(state),
200
+ authEvidence: state.authEvidence,
201
+ contextTokens: state.contextTokens,
202
+ contextCompacted: state.contextCompacted,
203
+ contextTokensError: state.contextTokensError,
204
+ };
205
+ }
206
+ function piFailure(state) {
207
+ if (state.failure !== undefined)
208
+ return state.failure;
209
+ if (state.sessionId === undefined)
210
+ return "Pi stream ended without valid session identity.";
211
+ if (!state.protocolComplete)
212
+ return "Pi stream ended before agent_settled.";
213
+ if (state.settledAborted)
214
+ return "Pi run settled after an abort.";
215
+ if (state.stopReason !== "stop")
216
+ return `Pi final assistant stop reason: ${state.stopReason ?? "missing"}.`;
217
+ return "Pi run settled without a meaningful final assistant result.";
218
+ }
219
+ function isPiAuthenticationError(message) {
220
+ return message
221
+ .split("\n")
222
+ .some((line) => /^(?:Error:\s*)?No API key found for [^\r\n]+\.\s*$/.test(line.trim()) ||
223
+ /^(?:Error:\s*)?Authentication failed for "[^"]+"[.:\s]/.test(line.trim()));
224
+ }
225
+ function piAuthenticationMessage(detail) {
226
+ const base = "Coding agent not authenticated: run `pi`, then `/login <provider>`, or configure " +
227
+ "the provider's credentials before running `aligndev code` again.";
228
+ return detail === undefined || detail.trim() === "" ? base : `${base}\n\n${detail}`;
229
+ }
@@ -17,6 +17,9 @@ const DEFAULT_QUOTA_PROCESS_ADAPTER = {
17
17
  export const readQuota = createQuotaReader();
18
18
  export function createQuotaReader(adapter = DEFAULT_QUOTA_PROCESS_ADAPTER, timeoutMs = QUOTA_TIMEOUT_MS) {
19
19
  return async (agent, context) => {
20
+ if (agent === "pi") {
21
+ throw new Error("Pi account quota is unsupported: check the selected provider's account limits directly.");
22
+ }
20
23
  const env = buildAgentEnv(context.env, context.unset);
21
24
  return agent === "claude"
22
25
  ? readClaudeQuota({ ...context, env: translateClaudePrivacyOptOut(env) }, adapter, timeoutMs)
@@ -6,6 +6,7 @@ export interface RunConfig {
6
6
  sessionFilePath: string;
7
7
  cwd: string;
8
8
  resume?: string;
9
+ quiet?: boolean;
9
10
  executableModel: string | undefined;
10
11
  skipPermissions: boolean;
11
12
  additionalDirectories: readonly string[];
@@ -27,6 +28,8 @@ export interface AgentProtocolState {
27
28
  authEvidence: boolean;
28
29
  contextTokens?: number;
29
30
  peakContextTokens?: number;
31
+ contextCompacted?: boolean;
32
+ contextTokensError?: string;
30
33
  streamTotalTokens?: number;
31
34
  }
32
35
  export interface AgentAssessment {
@@ -43,7 +46,7 @@ export interface AgentAdapter {
43
46
  executable: string;
44
47
  env?: Readonly<Record<string, string>>;
45
48
  buildArgs(config: RunConfig): string[];
46
- createState(): AgentProtocolState;
49
+ createState(config: RunConfig): AgentProtocolState;
47
50
  interpretLine(line: string, state: AgentProtocolState): string | undefined;
48
51
  assess(state: AgentProtocolState): AgentAssessment;
49
52
  isAuthenticationError(message: string): boolean;
@@ -18,9 +18,14 @@ const ASSISTANT_SESSION_VARIABLES = [
18
18
  "CODEX_THREAD_ID",
19
19
  "CODEX_CI",
20
20
  "CODEX_SANDBOX_NETWORK_DISABLED",
21
+ "PI_SESSION_ID",
22
+ "PI_SESSION_FILE",
23
+ "PI_PROVIDER",
24
+ "PI_MODEL",
25
+ "PI_REASONING_LEVEL",
21
26
  ];
22
27
  export async function runAgent(config, adapter, out, spawnProcess = spawnDirectChild) {
23
- const state = adapter.createState();
28
+ const state = adapter.createState(config);
24
29
  const outcome = await spawnAgent(config, adapter, state, out, spawnProcess);
25
30
  const assessment = adapter.assess(state);
26
31
  const failed = outcome.exitCode !== 0 || !assessment.succeeded;
@@ -111,7 +116,8 @@ function emitLine(config, adapter, line, state, out) {
111
116
  if (rendered === undefined)
112
117
  return;
113
118
  appendTranscript(config.sessionFilePath, `${rendered}\n`);
114
- out.write(`${rendered}\n`);
119
+ if (config.quiet !== true)
120
+ out.write(`${rendered}\n`);
115
121
  }
116
122
  function drainLines(buffer, onLine) {
117
123
  const lines = buffer.split("\n");
@@ -126,6 +132,10 @@ export function buildAgentEnv(baseEnv, unset) {
126
132
  const env = { ...baseEnv };
127
133
  for (const name of ASSISTANT_SESSION_VARIABLES)
128
134
  delete env[name];
135
+ if (env.PI_CODING_AGENT === "true")
136
+ delete env.PI_CODING_AGENT;
137
+ if (env.AI_AGENT === "pi")
138
+ delete env.AI_AGENT;
129
139
  for (const name of unset) {
130
140
  const trimmed = name.trim();
131
141
  if (trimmed !== "")
@@ -195,12 +205,14 @@ export function buildTerminationUpdate(signal, state, now) {
195
205
  result: `Terminated by ${signal} before completion.`,
196
206
  contextTokens: state.contextTokens ?? null,
197
207
  contextCompacted: isCompacted(state),
198
- contextTokensError: null,
208
+ contextTokensError: state.contextTokensError ?? null,
199
209
  };
200
210
  }
201
211
  // Occupancy only falls when the agent compacts the conversation, so a peak above the final figure
202
212
  // is the compaction itself.
203
213
  export function isCompacted(state) {
214
+ if (state.contextCompacted !== undefined)
215
+ return state.contextCompacted;
204
216
  const { contextTokens, peakContextTokens } = state;
205
217
  if (contextTokens === undefined || peakContextTokens === undefined)
206
218
  return false;
@@ -226,7 +226,7 @@ export function parseFrontmatter(block) {
226
226
  };
227
227
  }
228
228
  function parseAgent(raw) {
229
- return raw === "claude" || raw === "codex" ? raw : null;
229
+ return raw === "claude" || raw === "codex" || raw === "pi" ? raw : null;
230
230
  }
231
231
  function parsePid(raw) {
232
232
  if (raw === null || raw === undefined)
package/dist/config.js CHANGED
@@ -77,15 +77,18 @@ function resolveAgent(config, env) {
77
77
  if (detected.length === 1)
78
78
  return detected[0];
79
79
  const problem = detected.length === 0
80
- ? "no coding agent detected: run aligndev from Claude Code or Codex, or set"
81
- : "both Claude Code and Codex detected: set";
80
+ ? `no coding agent detected (${CODING_AGENTS.join(", ")}): run from a supported agent, or set`
81
+ : `multiple coding agents detected (${detected.join(", ")}): set`;
82
82
  throw new Error(`Error: ${problem} "code.agent" (${CODING_AGENTS.join(" or ")}) in ${config.path}.`);
83
83
  }
84
84
  function checkDefaultModel(code, path) {
85
85
  if (code.defaultModel === undefined)
86
86
  return;
87
87
  const models = resolveModels(code.agent, code.models);
88
- if (models.includes(code.defaultModel))
88
+ if (code.defaultModel.trim() === "") {
89
+ throw new Error(`Error: code.defaultModel must be nonblank, in ${path}.`);
90
+ }
91
+ if (models === undefined || models.includes(code.defaultModel))
89
92
  return;
90
93
  throw new Error(`Error: code.defaultModel must be one of: ${models.join(", ")}, in ${path}.`);
91
94
  }
@@ -1,4 +1,4 @@
1
1
  import type { CodingAgent } from "../code/coding-agent.js";
2
2
  import type { CommandForms } from "../command-form.js";
3
3
  import type { Platform } from "../config.js";
4
- export declare function renderCodeGuide(platform: Platform, agent: CodingAgent, models: readonly string[], defaultModel: string | undefined, forms: CommandForms): string;
4
+ export declare function renderCodeGuide(platform: Platform, agent: CodingAgent, models: readonly string[] | undefined, defaultModel: string | undefined, forms: CommandForms): string;
@@ -2,11 +2,19 @@ import { renderGuideTemplate } from "./render-template.js";
2
2
  export function renderCodeGuide(platform, agent, models, defaultModel, forms) {
3
3
  return renderGuideTemplate("code.md", { platform }, forms, {
4
4
  AGENT: agent,
5
- AUTH_COMMAND: agent === "claude" ? "`claude`, then `/login`" : "`codex login`",
6
- PERMISSIONS: agent === "claude"
7
- ? "Normal runs use `--permission-mode auto`, plus `--add-dir <companion>` for a project with a companion directory. `code.skipPermissions: true` in the aligndev settings selects `--dangerously-skip-permissions`"
8
- : "Normal runs use `--sandbox workspace-write`, plus `--add-dir <companion>` for a project with a companion directory. `code.skipPermissions: true` in the aligndev settings selects `--dangerously-bypass-approvals-and-sandbox`",
9
- MODELS: models.map((model) => `\`${model}\``).join(", "),
5
+ AUTH_COMMAND: agent === "pi"
6
+ ? "`pi`, then `/login <provider>`, or configure provider credentials"
7
+ : agent === "claude"
8
+ ? "`claude`, then `/login`"
9
+ : "`codex login`",
10
+ PERMISSIONS: agent === "pi"
11
+ ? "Pi uses ordinary OS permissions, including companion access. `code.skipPermissions` has no effect. Saved project trust is honored; no forced approval is passed"
12
+ : agent === "claude"
13
+ ? "Normal runs use `--permission-mode auto`, plus `--add-dir <companion>` for a project with a companion directory. `code.skipPermissions: true` in the aligndev settings selects `--dangerously-skip-permissions`"
14
+ : "Normal runs use `--sandbox workspace-write`, plus `--add-dir <companion>` for a project with a companion directory. `code.skipPermissions: true` in the aligndev settings selects `--dangerously-bypass-approvals-and-sandbox`",
15
+ MODEL_POLICY: models === undefined
16
+ ? "Any nonblank pi-native selector, preferably `provider/model` (thinking suffixes supported)"
17
+ : `One of ${models.map((model) => `\`${model}\``).join(", ")}`,
10
18
  DEFAULT_MODEL: defaultModel === undefined ? "the coding agent's default" : `\`${defaultModel}\``,
11
19
  ALIGNFIRST_SETUP: forms.viaNpx
12
20
  ? "The project must be prepared for AlignFirst. `npx -y aligndev` runs the `alignfirst` CLI through `npx`."
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "aligndev",
3
- "version": "0.23.3",
3
+ "version": "0.24.0",
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.",
@@ -66,32 +66,66 @@ If the frontmatter's `exitReason` is `auth_required`, the coding agent is not au
66
66
  {{#codingAgent}}
67
67
  ## How it runs
68
68
 
69
- `{{ALIGNDEV}} code` runs the agent in the **foreground** and blocks until it finishes, streaming the transcript to stdout. It never backgrounds or detaches itself.
69
+ `{{ALIGNDEV}} code` runs the agent in the **foreground** until it exits. It never backgrounds or detaches itself. By default it streams the transcript to stdout; `--quiet` suppresses that stream while preserving the durable session file and control/diagnostic output.
70
70
 
71
- Its first line, `Session file: <path>`, names the run's session file, the durable record of the run; retain that path. The file may live in the project's companion directory. Its frontmatter carries `status` (`running` → `succeeded`/`failed`) and the `sessionId`, and the `---- Result ----` block holds the outcome.
71
+ Choose the launch facility from your **parent host**, independently of the selected child `{{AGENT}}`. `code.agent` selects the child only. All three children (Claude Code, Codex, Pi) remain available from any supported parent.
72
72
 
73
- Coding runs can be long (several hours is fine), and a foreground command is subject to your tool timeout (10 minutes in Claude Code). **Always start `{{ALIGNDEV}} code` with your own background-execution facility, with no time limit.** Never detach it with `&` or a detach wrapper.
73
+ **One protocol run at a time per worktree and per ticket** — protocol runs share the working tree, and the ticket's work files. Finish (or cancel) the current protocol run before launching or resuming another. Plain messages (answers, questions) can be sent at any time.
74
74
 
75
- Run `{{ALIGNDEV}} code` outside your sandbox: the agent needs network access, and it writes outside the project, to its own session storage and possibly to the companion directory. In Codex, request escalated permissions for the command. In Claude Code with sandboxing enabled, run it with the sandbox disabled.
75
+ ## Background runs and reporting
76
76
 
77
- **One protocol run at a time per worktree and per ticket** — protocol runs share the working tree, and the ticket's work files. Finish (or kill) the current protocol run before launching or resuming another. Plain messages (answers, questions) can be sent at any time.
77
+ ### Pi parent
78
78
 
79
- ## Background runs and reporting
79
+ Before launching, establish that the `background` tool is available and that this parent stays alive after its acknowledgement. A one-shot print/JSON process is not a persistent assistant. Missing capability is an installation problem: explain that the parent needs `pi install npm:@alignfirst/pi-background`. The AlignDev skill alone supplies no executable tools. Do not substitute a blocking ordinary bash call, shell `&`, `nohup`, or a detach wrapper, or promise a wake without the facility.
80
80
 
81
- Once the run is started, end the turn telling the user, in their language, that the agent is working. Do not poll the run. A run is pending until you report its outcome.
81
+ Retain these distinct values for each run:
82
82
 
83
- - When your harness wakes the session as the command exits (Claude Code does), follow "After a run completes" on that wake.
84
- - Otherwise (Codex has no such wake today), the report waits for the user's next message. At the start of each later user turn, before anything else, check every pending run with `{{ALIGNDEV}} code status <session-file>`, and report the ones that finished.
83
+ - The original absolute worktree and this parent conversation's identity.
84
+ - The returned background job handle (`job.id`), which authorizes job status and cancellation.
85
+ - A fresh unique per-run `--meta` key, never reused for a successor or resume.
86
+ - The exact AlignDev session-file path once resolved, including a companion location when applicable.
87
+ - The child conversation ID (`sessionId`) for resume. It is neither a job handle nor a run-file path.
85
88
 
86
- ## After a run completes
89
+ Prepare the literal delegated prompt in a UTF-8 file, then launch the ordinary quoted shell command through `background` with `action: "start"` and `cwd`. Supply `--quiet --meta <unique-run-key>` yourself; the extension never parses or appends CLI options. This example assumes `/tmp/aligndev-request.txt` already contains the request. Generate a fresh key for every actual launch; the UUID below illustrates one run:
90
+
91
+ ```json
92
+ {"action":"start","command":"{{ALIGNDEV}} code new --message-file '/tmp/aligndev-request.txt' --quiet --meta 'a20bc7c1-c056-4d07-8cc2-90fe491a6df6'","cwd":"/srv/projects/example","label":"coding run"}
93
+ ```
94
+
95
+ For resume, use `{{ALIGNDEV}} code resume <sessionId> --message-file <path> --quiet --meta <fresh-run-key>` from the original worktree. A Pi child must resume from its recorded directory. Use safe shell quoting for paths and options; never interpolate raw user text into a command. A quoted heredoc with `--message-file -` is another literal-input route.
96
+
97
+ Start returns after OS spawn acknowledgement. Retain its handle, key and cwd immediately; **do not wait for the `Session file:` control line**. End the launch turn with an acknowledgement in the user's language, then call no tool and do not poll while waiting. Natural completion requests an idle turn or a follow-up after busy work. A completion notice is only a wake hint.
98
+
99
+ On a notice:
100
+
101
+ 1. Query `background` with `{"action":"status","id":"<returned-job-id>"}` first. This event-triggered ownership check is not a waiting or polling loop. Disregard an inactive origin or an unknown/retired/cleared handle: it can be a stale native notice after clear, navigation or reload and authorizes no workflow action. A still-running job authorizes no completion report.
102
+ 2. For a current-owner terminal job, run `{{ALIGNDEV}} code status <exact-file> --result` from its original worktree. If the path is not yet known, use `{{ALIGNDEV}} code status --meta <unique-run-key> --result` there. Resolve the returned `sessionFile:` relative to that worktree when necessary, retain its exact path, and use that path thereafter. Never fall back to the newest workspace or ticket run when identity is unknown. A launch can fail before creating a run file; report that failure rather than choosing another run.
103
+ 3. Read the authoritative status, `exitReason`, child `sessionId` and final Result from this response. `--result` excludes the transcript; the CLI imposes no numeric byte cap on final result text. Background output contains only quiet control/diagnostic output. Inspect it with `action: "output"`, or inspect the durable transcript, only for a specific diagnostic need.
104
+ 4. Continue authorized verification and dependent work, or ask genuine user questions and report authentication failures or blockers. One child turn does not complete the whole request. Record which outcome you handled so a repeated notice cannot duplicate reporting or launch successor work twice. Never rerun coding merely to retry reporting.
105
+
106
+ Cancel through `background` with `{"action":"stop","id":"<returned-job-id>"}`. It gives attached work a five-second graceful window before escalation, allowing the CLI to seal its durable file. Preserve session files; `clear` removes only a terminal generic job record and its retained output.
87
107
 
88
- Run `{{ALIGNDEV}} code status <session-file>`. This reconciles a stale `running` record before reporting its status. Then read the session file and report the outcome to the user in this conversation. If the run failed, say so plainly and propose the next step; don't silently retry.
108
+ **Host limits:** standalone manual compaction or cancelled/failed navigation can delay a notice until another ordinary turn. Interruption or native queue clearing can lose automatic continuation. Already-submitted notices can appear after navigation or reload; validate ownership as above. Delivery is not exactly once. Normal shutdown, session replacement, successful tree navigation and `/reload` cancel owned work; crash recovery is not promised.
89
109
 
90
- An `exitReason` of `auth_required` in the frontmatter (`{{ALIGNDEV}} code` also exits `2`) means the coding agent is not authenticated on this machine. Tell the user to authenticate with {{AUTH_COMMAND}}, and do not retry.
110
+ Pi uses ordinary OS permissions and saved project trust, not an implied sandbox. `code.skipPermissions` does not elevate Pi or force project approval.
91
111
 
92
- Don't reconstruct what happened: no re-running the agent, no `git` archaeology to double-check its account — the session file is authoritative for that. Verifying the result is different: run the verification your operating instructions prescribe before reporting. A failing check is new work, in a new agent run.
112
+ ### Claude Code parent
93
113
 
94
- Keep session files in place; they are the durable audit trail.
114
+ Coding runs can be long (several hours is fine), and a foreground command is subject to your tool timeout (10 minutes in Claude Code). Use your own background-execution facility with no time limit. When sandboxing is enabled, run `{{ALIGNDEV}} code` with the sandbox disabled: the child needs network and writes outside the project. Retain the initial `Session file: <path>` control line. End the launch turn on its acknowledgement without polling; follow "After a run completes" when the harness wakes the session as the command exits.
115
+
116
+ ### Codex parent
117
+
118
+ Use your established background-execution facility with no time limit and request escalated permissions for `{{ALIGNDEV}} code`. Retain the initial `Session file: <path>` control line. End the launch turn on its acknowledgement without polling. Where no completion bridge is configured, the report waits for the user's next message. At the start of each later user turn, before anything else, check every pending run with `{{ALIGNDEV}} code status <session-file>`, and report the ones that finished. This fallback does not assert that Codex lacks native queue capability.
119
+
120
+ Neither parent detaches with `&` or a wrapper. A run is pending until its outcome is handled.
121
+
122
+ ## After a run completes
123
+
124
+ **Pi parent:** use the ownership and result-only procedure above. **Claude Code or Codex parent:** run `{{ALIGNDEV}} code status <session-file>` to reconcile stale status, then read the session file and report in this conversation.
125
+
126
+ An `exitReason` of `auth_required` (`{{ALIGNDEV}} code new/resume` exits `2`) means the selected child is not authenticated on this machine. Tell the user to authenticate with {{AUTH_COMMAND}}, and do not retry. Other launch/run failures exit `1`; success exits `0`. A successful `status` query exits `0` even for a failed run: read its `status` and `exitReason`.
127
+
128
+ Don't reconstruct what happened: no re-running the agent, no `git` archaeology to double-check its account — the session file is authoritative for that. Run the verification your operating instructions prescribe. A failing check is new work, in a new agent run; do not silently retry. Keep session files as the durable audit trail.
95
129
  {{/codingAgent}}
96
130
 
97
131
  ## CLI reference
@@ -101,7 +135,14 @@ Keep session files in place; they are the durable audit trail.
101
135
  {{ALIGNDEV}} code new --catchup --ticket <id> [--protocol <protocol>] [--message-file <path|->]
102
136
  {{ALIGNDEV}} code new --message "..."
103
137
  {{ALIGNDEV}} code resume <sessionId> [--protocol <protocol>] [--message "..."]
138
+ {{#openclaw}}
104
139
  {{ALIGNDEV}} code status (<session-file> | --ticket <id> | --no-ticket)
140
+ {{/openclaw}}
141
+ {{#codingAgent}}
142
+ {{ALIGNDEV}} code new --message-file <path> --quiet --meta <unique-run-key>
143
+ {{ALIGNDEV}} code resume <sessionId> --message-file <path> --quiet --meta <unique-run-key>
144
+ {{ALIGNDEV}} code status (<session-file> | --ticket <id> | --no-ticket | --meta <key>) [--result]
145
+ {{/codingAgent}}
105
146
  {{ALIGNDEV}} code quota
106
147
  ```
107
148
 
@@ -109,8 +150,14 @@ Keep session files in place; they are the durable audit trail.
109
150
  |---------|-------------|
110
151
  | `new` | Start a new session. |
111
152
  | `resume <sessionId>` | Continue an existing session. |
153
+ {{#openclaw}}
112
154
  | `status` | Reconcile and show one run's durable status, including `contextTokens`. Give the session file, or `--ticket <id>` / `--no-ticket` to select the newest run of that scope. Does not start the agent. |
113
155
  | `quota` | Show the selected coding agent's account limits and reset times. Takes no option. |
156
+ {{/openclaw}}
157
+ {{#codingAgent}}
158
+ | `status` | Reconcile and show one run's durable status, including `contextTokens`. Select exactly one file, `--ticket <id>`, `--no-ticket`, or `--meta <key>`; scope/key selectors choose their newest matching run. Does not start the agent. |
159
+ | `quota` | Show account limits and reset times for Claude Code/Codex. Unsupported for Pi; check the provider directly. Takes no option. |
160
+ {{/codingAgent}}
114
161
 
115
162
  | Option | Description |
116
163
  |--------|-------------|
@@ -120,12 +167,26 @@ Keep session files in place; they are the durable audit trail.
120
167
  | `--message "..."` | Message to send, written in English. `-m` is the short form. Required for `spec`, `aad`, and when neither `--protocol` nor `--catchup` is given. A message file also satisfies this requirement. |
121
168
  | `--message-file <path>` | Read a UTF-8 message file; `-` reads stdin. Mutually exclusive with `--message`. |
122
169
  | `--catchup` | Load the ticket history before the protocol and message. `new` only, requires a ticket. Alone, it returns a short synthesis. |
123
- | `--model <model>` | One of {{MODELS}}. A new session defaults to {{DEFAULT_MODEL}}; a resume keeps the session's model. Prefer the default (omit the flag). |
170
+ | `--model <model>` | {{MODEL_POLICY}}. A new session defaults to {{DEFAULT_MODEL}}; a resume keeps the session's model. Prefer the default (omit the flag). |
171
+ {{#openclaw}}
124
172
  | `--meta "..."` | Opaque handoff string stored verbatim in the session file's `meta:` frontmatter. `{{ALIGNDEV}} code` never reads it — it's for you to stash context the run's later reader needs (e.g. where to report the outcome). |
173
+ {{/openclaw}}
174
+ {{#codingAgent}}
175
+ | `--meta <key>` | On `new/resume`, store an opaque handoff key verbatim. On `status`, select the newest run with that exact key anywhere in the active session tree. Use a unique key per run for exact asynchronous lookup. |
176
+ | `--quiet` | `new/resume` only. Suppress live transcript stdout, preserving the durable transcript, initial `Session file:` line, new `Session ID:`, and failure diagnostics. |
177
+ | `--result` | `status` only. Append a terminal run's final Result when present, without transcript output. Running runs show metadata only. No numeric final-text byte cap. |
178
+ {{/codingAgent}}
125
179
 
180
+ {{#openclaw}}
126
181
  The current coding agent is `{{AGENT}}`. `code.models` in the aligndev settings 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.
127
182
 
128
183
  `{{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 follows the selected agent's available account limits.
184
+ {{/openclaw}}
185
+ {{#codingAgent}}
186
+ The current coding agent is `{{AGENT}}`. A nonempty `code.models` in the aligndev settings 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 `code.defaultModel`, else Pi's own default; a resume keeps 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.
187
+
188
+ `{{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; Pi quota is unsupported.
189
+ {{/codingAgent}}
129
190
 
130
191
  `contextTokens` is what the run left in the agent's context window, measured from its last model response. It describes the conversation, so resuming a session carries the figure forward and each run reports a larger one.
131
192
 
@@ -133,7 +194,12 @@ The current coding agent is `{{AGENT}}`. `code.models` in the aligndev settings
133
194
 
134
195
  {{PERMISSIONS}}.
135
196
 
197
+ {{#openclaw}}
136
198
  For `new` runs, the `Session ID:` is printed to stdout and written with `agent: {{AGENT}}` in the session file frontmatter. Save it to resume the conversation later. Resume requires the same selected agent; agentless legacy sessions require a new session.
199
+ {{/openclaw}}
200
+ {{#codingAgent}}
201
+ For `new` runs, the child `Session ID:` is printed to stdout and recorded as `sessionId` with `agent: {{AGENT}}` in the durable session file. An asynchronous Pi parent retains it from authoritative `status --result` retrieval, without waiting at launch. Save it for resume, which requires the same selected child; agentless legacy sessions require a new session.
202
+ {{/codingAgent}}
137
203
 
138
204
  **No protocol or catchup:** the message is sent as-is (no AlignFirst command). Use it to answer the agent's questions in an existing session, execute a plan in a new session, or ask a question:
139
205
 
@@ -62,7 +62,12 @@ The message carries the complete question, however detailed, the selected branch
62
62
  The message carries the complete question, however detailed, the selected branch, and an explicit constraint to investigate and answer without implementing changes. Use the delegation guide's background launch and completion procedure.
63
63
  {{/codingAgent}}
64
64
 
65
+ {{#openclaw}}
65
66
  Retain the printed session id. Later turns of the same topic resume that session, so the discussion accumulates in one place.
67
+ {{/openclaw}}
68
+ {{#codingAgent}}
69
+ Retain the child session id, from authoritative completion retrieval for an asynchronous Pi launch. Follow the delegation guide instead of waiting for it at launch. Later turns of the same topic resume that session, so the discussion accumulates in one place.
70
+ {{/codingAgent}}
66
71
 
67
72
  ## Step 4 — Relay
68
73
 
@@ -16,13 +16,18 @@ The choice rests on the metadata alone. The playbook tells you what to do. No an
16
16
  You are the AlignFirst assistant in a coding-agent session, and the user talks to you in this conversation. Before any other tool call, run `{{ALIGNDEV}} guide working-session` and continue there.
17
17
  {{/codingAgent}}
18
18
 
19
+ {{#openclaw}}
19
20
  **The agent** — the coding agent (Claude Code or Codex) you launch in a project with `{{ALIGNDEV}} code`. It reads and changes the codebase; you guide it.
21
+ {{/openclaw}}
22
+ {{#codingAgent}}
23
+ **The agent** — the selected child (Claude Code, Codex or Pi) you launch in a project with `{{ALIGNDEV}} code`. It reads and changes the codebase; you guide it.
24
+ {{/codingAgent}}
20
25
 
21
26
  {{#openclaw}}
22
27
  You run inside OpenClaw, but you are the assistant, never an agent. "The agent" always means the coding agent you launch.
23
28
  {{/openclaw}}
24
29
  {{#codingAgent}}
25
- You run inside Claude Code or Codex, but you are the assistant, never an agent. "The agent" always means the coding agent you launch.
30
+ You run inside Claude Code, Codex or Pi as the parent assistant. "The agent" always means the selected child, independently of your host.
26
31
 
27
32
  Your own tools could edit the code, but you delegate: you never implement, investigate, or modify the codebase yourself.
28
33
  {{/codingAgent}}
@@ -126,7 +131,7 @@ Coding runs are long. Run `{{ALIGNDEV}} code` through `exec` in the background,
126
131
  For a `target` parameter, keep the whole `chat_id`, prefix included (e.g. `"channel:#####"`). Never reconstruct, paraphrase, or guess a `chat_id`. A `threadId` parameter is different: pass only the bare thread ID from the conversation metadata or tool result, never a `thread:<channel>/<id>` target.
127
132
  {{/openclaw}}
128
133
  {{#codingAgent}}
129
- To delegate, run `{{ALIGNDEV}} code` from the workplace, or from PROJECT_PATH for operational work. Before your first `{{ALIGNDEV}} code` run of a session, run `{{ALIGNDEV}} guide code` and follow it — it is the delegation manual, and it stays the last guide you read. Delegation always goes through `{{ALIGNDEV}} code` — never your own subagents or tasks, and never an AlignFirst protocol skill run by yourself.
134
+ To delegate, run `{{ALIGNDEV}} code` from the workplace, or from PROJECT_PATH for operational work. Before your first `{{ALIGNDEV}} code` run of a session, run `{{ALIGNDEV}} guide code` and follow it — it is the delegation manual, and it stays the last guide you read. Delegation always goes through `{{ALIGNDEV}} code` — never your own subagents, `subagent` tool or tasks, and never an AlignFirst protocol skill run by yourself. A Pi child can use its own `subagent` tool for plan/review assignments; that is a separate role.
130
135
 
131
136
  Coding runs are long. Run `{{ALIGNDEV}} code` in the background, as the delegation guide describes.
132
137
  {{/codingAgent}}
@@ -147,7 +152,12 @@ Keep scratch artifacts out of tracked git directories.
147
152
 
148
153
  ## Vocabulary
149
154
 
155
+ {{#openclaw}}
150
156
  - **the agent** — the coding agent (Claude Code or Codex) you launch in a project with `{{ALIGNDEV}} code`. It reads and changes the codebase; you guide it. Call it _the agent_ with the user too.
157
+ {{/openclaw}}
158
+ {{#codingAgent}}
159
+ - **the agent** — the selected child (Claude Code, Codex or Pi) launched with `{{ALIGNDEV}} code`. Call it _the agent_ with the user too.
160
+ {{/codingAgent}}
151
161
  - **ticket** — an issue or card.
152
162
  - **project workspace** — in a project, it means branch + worktree + isolated dev server. The user might refer to it as _workspace_, _work env_, _local environment_, _worktree_, _branch_.
153
163
  - **dev server** (or *your server*) — the local instance of the project running in the worktree, with hot reload, etc. The user might refer to it as _server_, _local server_, or even the _env URL_.
@@ -227,7 +227,7 @@ The workspace is ready. Announce what you're about to do in one line and do it.
227
227
  When the work is an `{{ALIGNDEV}} code` run, launch it as the delegation guide describes: background `exec` with `timeoutSeconds: 0`, then end the turn on the acknowledgement. Call nothing on the `{{ALIGNDEV}} code` session before the chained turn wakes you, whatever the `exec` acknowledgement suggests.
228
228
  {{/openclaw}}
229
229
  {{#codingAgent}}
230
- When the work is an `{{ALIGNDEV}} code` run, launch it in the background as the delegation guide describes, then end the turn on the acknowledgement.
230
+ When the work is an `{{ALIGNDEV}} code` run, follow the delegation guide's parent-host route, then end the launch turn on the acknowledgement. A Pi parent first requires the available `background` tool and a persistent session; if either is missing, explain the setup problem instead of launching or promising completion.
231
231
  {{/codingAgent}}
232
232
 
233
233
  Ask only when you genuinely can't proceed — the request is ambiguous enough that two readings lead to different work, or it turns on a product decision that isn't yours to make.
@@ -315,7 +315,12 @@ Feel free to do the rest yourself (except coding) when it's more practical.
315
315
 
316
316
  ### A background run moves the report
317
317
 
318
+ {{#openclaw}}
318
319
  Launching a background run ends the turn: the closing message is the launch acknowledgement, and the report moves to the run's completion turn. Each further run launched from that turn moves the report again.
320
+ {{/openclaw}}
321
+ {{#codingAgent}}
322
+ Launching a background run ends the turn on its acknowledgement. For a Pi parent, first verify the `background` capability and a persistent parent, as the delegation guide requires; without them, explain installation instead of promising a later report. On a Pi notice, validate the job handle and retrieve the exact run with `status --result`. Continue authorized work or report genuine questions/blockers. A child's completed turn is not completion of the whole request. Further runs use the same launch procedure; repeated notices must not duplicate successor work. Claude Code and Codex retain their host-specific completion/fallback routes in the delegation guide.
323
+ {{/codingAgent}}
319
324
 
320
325
  ### The plan is not a gate
321
326
 
@@ -471,7 +476,12 @@ Either way, the report states the error and your decision.
471
476
 
472
477
  #### Dev-server log review
473
478
 
479
+ {{#openclaw}}
474
480
  After using a dev-server, have a separate no-protocol agent run with the smallest available model inspect its logs: give it the log locations and ask for errors or unusual behavior. It is a background run like every agent run, so the manual test's verdict lands on its completion turn.
481
+ {{/openclaw}}
482
+ {{#codingAgent}}
483
+ After using a dev-server, have a separate no-protocol agent run inspect its logs: give it the log locations and ask for errors or unusual behavior. Choose the smallest available model from the child's ordered list; for Pi without a finite ordered allowlist, use the configured/default model instead. Launch and retrieve its result through the delegation guide's parent-host route before reporting the manual test's verdict.
484
+ {{/codingAgent}}
475
485
 
476
486
  Clean logs are required for the manual test to pass.
477
487