aligndev 0.24.0 → 0.26.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 (42) hide show
  1. package/README.md +73 -15
  2. package/dist/alignfirst-cli.d.ts +2 -0
  3. package/dist/alignfirst-cli.js +62 -1
  4. package/dist/cli.js +8 -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 +6 -3
  8. package/dist/code/code-cli.js +136 -63
  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.js +1 -1
  14. package/dist/code/models.d.ts +2 -2
  15. package/dist/code/models.js +20 -15
  16. package/dist/code/native-context.d.ts +2 -0
  17. package/dist/code/native-context.js +21 -0
  18. package/dist/code/pi-agent.js +12 -1
  19. package/dist/code/quota-process.d.ts +9 -0
  20. package/dist/code/quota-process.js +165 -0
  21. package/dist/code/quota.d.ts +2 -3
  22. package/dist/code/quota.js +91 -100
  23. package/dist/code/run-agent.d.ts +8 -2
  24. package/dist/code/run-agent.js +33 -16
  25. package/dist/code/session-file.d.ts +3 -0
  26. package/dist/code/session-file.js +32 -9
  27. package/dist/config.d.ts +44 -7
  28. package/dist/config.js +210 -44
  29. package/dist/guide/code-guide.d.ts +2 -2
  30. package/dist/guide/code-guide.js +10 -7
  31. package/dist/guide/guide-cli.js +16 -7
  32. package/dist/json-shape.d.ts +5 -3
  33. package/dist/json-shape.js +39 -12
  34. package/dist/package-version.d.ts +1 -0
  35. package/dist/package-version.js +7 -0
  36. package/dist/project/layout.d.ts +4 -0
  37. package/dist/project/layout.js +29 -11
  38. package/dist/project/render.js +3 -1
  39. package/dist/project/status.d.ts +2 -1
  40. package/dist/project/status.js +1 -0
  41. package/package.json +4 -4
  42. package/templates/guide/code.md +32 -11
@@ -1,7 +1,9 @@
1
1
  import { parseArgs } from "node:util";
2
2
  import { resolveModels } from "../code/models.js";
3
+ import { describeNativeStorage } from "../code/native-context.js";
3
4
  import { PLATFORMS, requireProjectsRoot, resolveCodeConfig, } from "../config.js";
4
5
  import { errorMessage } from "../errors.js";
6
+ import { readProjectReport } from "../project/layout.js";
5
7
  import { renderProjectsGuideForRoot } from "../project/project-cli.js";
6
8
  import { renderCodeGuide } from "./code-guide.js";
7
9
  import { resolveGuideFile } from "./guide-file.js";
@@ -23,6 +25,7 @@ function parseGuideArgs(tokens) {
23
25
  args: tokens,
24
26
  options: {
25
27
  root: { type: "string" },
28
+ profile: { type: "string" },
26
29
  help: { type: "boolean", short: "h", default: false },
27
30
  },
28
31
  strict: true,
@@ -34,12 +37,15 @@ function parseGuideArgs(tokens) {
34
37
  if (values.root !== undefined && topic !== "project") {
35
38
  throw new Error("Error: --root is valid only with `aligndev guide project`.");
36
39
  }
37
- return { topic, root: values.root, help: values.help };
40
+ if (values.profile !== undefined && topic !== "code") {
41
+ throw new Error("Error: --profile is valid only with `aligndev guide code`.");
42
+ }
43
+ return { topic, root: values.root, profile: values.profile, help: values.help };
38
44
  }
39
45
  function renderUsage(forms) {
40
46
  const playbookTopics = PLATFORMS.map((platform) => ` ${platform}: ${PLAYBOOK_TOPICS[platform].join(", ")}`);
41
47
  return `Usage:
42
- ${forms.aligndev} guide [<topic>] [--root <path>]
48
+ ${forms.aligndev} guide [<topic>] [--root <path>] [--profile <name>]
43
49
  ${forms.aligndev} guide --help
44
50
 
45
51
  Without a topic, prints the playbook of the platform set in the aligndev settings.
@@ -54,16 +60,19 @@ ${playbookTopics.join("\n")}
54
60
  }
55
61
  function renderTopic(args, config, ctx) {
56
62
  if (args.topic === "code")
57
- return renderCodeTopic(config, ctx);
63
+ return renderCodeTopic(config, ctx, args.profile);
58
64
  if (args.topic === "project" && config.platform === "openclaw") {
59
65
  return renderProjectsGuideForRoot({ ...ctx, projectsRoot: config.projectsRoot }, args.root);
60
66
  }
61
67
  return renderPlaybookTopic(args.topic, config, ctx);
62
68
  }
63
- function renderCodeTopic(config, ctx) {
64
- const code = resolveCodeConfig(config, ctx.env);
65
- const models = resolveModels(code.agent, code.models);
66
- return renderCodeGuide(config.platform, code.agent, models, code.defaultModel, ctx.forms);
69
+ function renderCodeTopic(config, ctx, profile) {
70
+ const report = readProjectReport(ctx.alignfirstCommand, ctx.cwd, ctx.env);
71
+ if ("error" in report)
72
+ throw new Error(report.error);
73
+ const code = resolveCodeConfig(config, ctx.env, { project: report.aligndev, explicit: profile });
74
+ const models = resolveModels(code.agent, code.models, code.modelAliases);
75
+ return renderCodeGuide(config.platform, code.agent, models, code.defaultModel, ctx.forms, code.profile, describeNativeStorage(code));
67
76
  }
68
77
  function renderPlaybookTopic(topic, config, ctx) {
69
78
  if (topic !== undefined)
@@ -1,4 +1,4 @@
1
- export type Check<T> = (value: unknown, path: string) => T;
1
+ export type Check<T> = (value: unknown, path: string, warningPath?: string) => T;
2
2
  export interface OptionalField<T> {
3
3
  optional: Check<T>;
4
4
  }
@@ -7,8 +7,10 @@ type Fields<T> = {
7
7
  };
8
8
  /** Runs `check` at the root; a shape failure becomes `toError(<message>)`. */
9
9
  export declare function parseShape<T>(check: Check<T>, value: unknown, toError: (detail: string) => Error): T;
10
- /** Rejects the first unknown key, then checks each field in declaration order. */
11
- export declare function object<T extends object>(fields: Fields<T>): Check<T>;
10
+ export declare function object<T extends object>(fields: Fields<T>, onUnknown?: (path: string, key: string) => void): Check<T>;
11
+ export declare function record<T>(check: Check<T>, keyCheck?: Check<string>): Check<Record<string, T>>;
12
+ export declare function nonblankString(value: unknown, path: string): string;
13
+ export declare function nulFreeString(value: unknown, path: string): string;
12
14
  export declare function optional<T>(check: Check<T>): OptionalField<T>;
13
15
  export declare function literal<const T extends readonly (string | number)[]>(...values: T): Check<T[number]>;
14
16
  export declare function integerBetween(min: number, max: number): Check<number>;
@@ -12,27 +12,54 @@ export function parseShape(check, value, toError) {
12
12
  throw error;
13
13
  }
14
14
  }
15
- /** Rejects the first unknown key, then checks each field in declaration order. */
16
- export function object(fields) {
15
+ export function object(fields, onUnknown) {
17
16
  const entries = Object.entries(fields);
18
- return (value, path) => {
17
+ return (value, path, warningPath = path) => {
19
18
  if (!isPlainObject(value))
20
19
  throw shapeError(path, "be an object");
21
- const unknownKey = Object.keys(value).find((key) => !Object.hasOwn(fields, key));
22
- if (unknownKey !== undefined)
23
- throw shapeError(childPath(path, unknownKey), "be removed");
20
+ for (const key of Object.keys(value)) {
21
+ if (Object.hasOwn(fields, key))
22
+ continue;
23
+ if (onUnknown === undefined)
24
+ throw shapeError(childPath(path, key), "be removed");
25
+ onUnknown(warningPath, key);
26
+ }
24
27
  const result = {};
25
28
  for (const [key, field] of entries) {
26
29
  const fieldPath = childPath(path, key);
30
+ const fieldWarningPath = childPath(warningPath, key);
27
31
  if (typeof field === "function")
28
- result[key] = field(value[key], fieldPath);
32
+ result[key] = field(value[key], fieldPath, fieldWarningPath);
29
33
  else if (value[key] !== undefined)
30
- result[key] = field.optional(value[key], fieldPath);
34
+ result[key] = field.optional(value[key], fieldPath, fieldWarningPath);
31
35
  }
32
36
  // The fields mirror T key by key.
33
37
  return result;
34
38
  };
35
39
  }
40
+ export function record(check, keyCheck = string) {
41
+ return (value, path, warningPath = path) => {
42
+ if (!isPlainObject(value))
43
+ throw shapeError(path, "be an object");
44
+ return Object.fromEntries(Object.entries(value).map(([key, item]) => {
45
+ const fieldPath = childPath(path, key);
46
+ keyCheck(key, fieldPath);
47
+ return [key, check(item, fieldPath, `${warningPath}[<entry>]`)];
48
+ }));
49
+ };
50
+ }
51
+ export function nonblankString(value, path) {
52
+ const text = string(value, path);
53
+ if (text.trim() === "")
54
+ throw shapeError(path, "be nonblank");
55
+ return text;
56
+ }
57
+ export function nulFreeString(value, path) {
58
+ const text = string(value, path);
59
+ if (text.includes("\u0000"))
60
+ throw shapeError(path, "contain no NUL characters");
61
+ return text;
62
+ }
36
63
  function isPlainObject(value) {
37
64
  if (typeof value !== "object" || value === null)
38
65
  return false;
@@ -98,16 +125,16 @@ export function matching(pattern) {
98
125
  };
99
126
  }
100
127
  export function arrayOf(check) {
101
- return (value, path) => {
128
+ return (value, path, warningPath = path) => {
102
129
  if (!Array.isArray(value))
103
130
  throw shapeError(path, "be an array");
104
- return value.map((item, index) => check(item, bracketPath(path, String(index))));
131
+ return value.map((item, index) => check(item, bracketPath(path, String(index)), bracketPath(warningPath, String(index))));
105
132
  };
106
133
  }
107
134
  export function nonEmptyArrayOf(check) {
108
135
  const checkArray = arrayOf(check);
109
- return (value, path) => {
110
- const items = checkArray(value, path);
136
+ return (value, path, warningPath = path) => {
137
+ const items = checkArray(value, path, warningPath);
111
138
  if (items.length === 0)
112
139
  throw shapeError(path, "be a non-empty array");
113
140
  return items;
@@ -0,0 +1 @@
1
+ export declare function readPackageVersion(): string;
@@ -0,0 +1,7 @@
1
+ import { readFileSync } from "node:fs";
2
+ export function readPackageVersion() {
3
+ const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
4
+ if (pkg.version === undefined)
5
+ throw new Error("aligndev: package.json is missing 'version'");
6
+ return pkg.version;
7
+ }
@@ -5,8 +5,12 @@ export interface ProjectReport {
5
5
  cli: ProjectCliReport | null;
6
6
  config: ProjectConfigView | null;
7
7
  companion: CompanionReport | null;
8
+ aligndev: AligndevProjectSettings | null;
8
9
  locations: Record<ItemName, ItemLocation>;
9
10
  }
11
+ export interface AligndevProjectSettings {
12
+ profile: string;
13
+ }
10
14
  export type ConfigSource = "project" | "companion";
11
15
  export interface ProjectCliReport {
12
16
  installed: string;
@@ -1,10 +1,9 @@
1
- import { runAlignfirst } from "../alignfirst-cli.js";
1
+ import { describeAlignfirst, forwardSettingsWarnings, runAlignfirst } from "../alignfirst-cli.js";
2
2
  import { errorMessage } from "../errors.js";
3
- const MIN_ALIGNFIRST_VERSION = "0.9.0";
4
3
  export function readProjectReport(command, cwd, env) {
5
4
  const result = runAlignfirst(command, ["config", "--json"], cwd, env);
6
5
  if (result.status !== 0) {
7
- const error = firstLine(result.stderr);
6
+ const error = firstLine(forwardSettingsWarnings(result.stderr));
8
7
  return { error: error === "" ? "alignfirst config failed" : error };
9
8
  }
10
9
  let value;
@@ -12,22 +11,30 @@ export function readProjectReport(command, cwd, env) {
12
11
  value = JSON.parse(result.stdout);
13
12
  }
14
13
  catch (error) {
15
- throw new Error(`Invalid alignfirst config report for ${cwd}: ${errorMessage(error)}`);
14
+ throw new Error(`Invalid alignfirst config report for ${cwd}: ${errorMessage(error)} ${describeAlignfirst(command, cwd, env)}`);
15
+ }
16
+ if (isOutdatedReport(value)) {
17
+ return { error: `${outdatedAlignfirst(cwd)} ${describeAlignfirst(command, cwd, env)}` };
18
+ }
19
+ try {
20
+ return parseProjectReport(value, cwd);
21
+ }
22
+ catch (error) {
23
+ throw new Error(`${errorMessage(error)} ${describeAlignfirst(command, cwd, env)}`);
16
24
  }
17
- if (isOutdatedReport(value))
18
- return { error: outdatedAlignfirst(cwd) };
19
- return parseProjectReport(value, cwd);
20
25
  }
21
26
  function firstLine(value) {
22
27
  return value.trim().split("\n", 1)[0] ?? "";
23
28
  }
24
- // Before alignfirst 0.9.0, the report had no `.alignfirst-instructions` location.
29
+ // Detect the contract rather than the package version, including unreleased checkout builds.
25
30
  function isOutdatedReport(value) {
26
- return (isRecord(value) && !(isRecord(value.locations) && ".alignfirst-instructions" in value.locations));
31
+ return (isRecord(value) &&
32
+ (!Object.hasOwn(value, "aligndev") ||
33
+ !(isRecord(value.locations) && ".alignfirst-instructions" in value.locations)));
27
34
  }
28
35
  function outdatedAlignfirst(path) {
29
- return (`The alignfirst CLI used in ${path} is too old: aligndev requires alignfirst ` +
30
- `${MIN_ALIGNFIRST_VERSION} or later.`);
36
+ return (`The alignfirst CLI used in ${path} is too old: aligndev requires the profile-aware ` +
37
+ 'alignfirst config --json contract (top-level "aligndev"). Upgrade alignfirst.');
31
38
  }
32
39
  function parseProjectReport(value, path) {
33
40
  if (!isRecord(value))
@@ -37,9 +44,20 @@ function parseProjectReport(value, path) {
37
44
  cli: parseCli(value.cli, path),
38
45
  config: parseConfig(value.config, path),
39
46
  companion: parseCompanion(value.companion, path),
47
+ aligndev: parseAligndev(value.aligndev, path),
40
48
  locations: parseLocations(value.locations, path),
41
49
  };
42
50
  }
51
+ function parseAligndev(value, path) {
52
+ if (value === null)
53
+ return null;
54
+ if (!isRecord(value) ||
55
+ typeof value.profile !== "string" ||
56
+ value.profile.trim().length === 0 ||
57
+ Object.keys(value).some((key) => key !== "profile"))
58
+ throw invalidReport(path);
59
+ return { profile: value.profile };
60
+ }
43
61
  function parseSource(value, path) {
44
62
  if (value === "project" || value === "companion" || value === null)
45
63
  return value;
@@ -4,7 +4,7 @@ export function renderProjectList(inventory) {
4
4
  if (inventory.projects.length === 0)
5
5
  lines.push(" (none)");
6
6
  for (const project of inventory.projects) {
7
- lines.push(`- Name: ${renderOutputValue(project.name)}`, ` Path: ${renderOutputValue(project.path)}`, ` Directory: ${renderOutputValue(project.directory)}`, ` Port range: ${renderProjectRange(project.portRange, project.portRangeCode)}`, ` Workspaces: ${renderValues(project.workspaces)}`);
7
+ lines.push(`- Name: ${renderOutputValue(project.name)}`, ` Path: ${renderOutputValue(project.path)}`, ` Directory: ${renderOutputValue(project.directory)}`, ` Port range: ${renderProjectRange(project.portRange, project.portRangeCode)}`, ` AlignDev profile: ${renderNullableValue(project.description.aligndev?.profile ?? null)}`, ` Workspaces: ${renderValues(project.workspaces)}`);
8
8
  }
9
9
  lines.push("", "Directories:");
10
10
  if (inventory.directories.length === 0)
@@ -47,6 +47,7 @@ export function renderProjectListJson(inventory) {
47
47
  portRange: project.portRange ?? null,
48
48
  portRangeCode: project.portRangeCode ?? null,
49
49
  companion: project.description.companion,
50
+ aligndev: project.description.aligndev,
50
51
  locations: project.description.locations,
51
52
  workspaces: project.workspaces,
52
53
  })),
@@ -86,6 +87,7 @@ export function renderProjectStatus(details) {
86
87
  ` Port range: ${renderProjectRange(details.portRange ?? undefined, details.portRangeCode ?? undefined)}`,
87
88
  ` Config source: ${details.configSource ?? "(none)"}`,
88
89
  ` Companion: ${renderCompanion(details.companion)}`,
90
+ ` AlignDev profile: ${renderNullableValue(details.aligndev?.profile ?? null)}`,
89
91
  ` DEVELOPERS.md: ${renderLocation(details.locations["DEVELOPERS.md"])}`,
90
92
  ` Work files: ${renderLocation(details.locations[".plans"])}`,
91
93
  ` Work-files folder: ${renderNullableValue(details.plansFolder)}`,
@@ -1,5 +1,5 @@
1
1
  import type { ProjectInventory } from "./discovery.js";
2
- import type { CompanionReport, ConfigSource, ItemLocation, ItemName } from "./layout.js";
2
+ import type { AligndevProjectSettings, CompanionReport, ConfigSource, ItemLocation, ItemName } from "./layout.js";
3
3
  import type { PortRange } from "./markers.js";
4
4
  export interface ProjectDetails {
5
5
  name: string;
@@ -12,6 +12,7 @@ export interface ProjectDetails {
12
12
  ticketIdPattern: string | null;
13
13
  configSource: ConfigSource | null;
14
14
  companion: CompanionReport | null;
15
+ aligndev: AligndevProjectSettings | null;
15
16
  locations: Record<ItemName, ItemLocation>;
16
17
  workspaces: string[];
17
18
  worktrees: ProjectWorktree[];
@@ -34,6 +34,7 @@ function buildProjectDetails(project) {
34
34
  ticketIdPattern: project.description.config?.ticketIdPattern ?? null,
35
35
  configSource: project.description.source,
36
36
  companion: project.description.companion,
37
+ aligndev: project.description.aligndev,
37
38
  locations: project.description.locations,
38
39
  workspaces: project.workspaces,
39
40
  worktrees: readWorktrees(project.path),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "aligndev",
3
- "version": "0.24.0",
3
+ "version": "0.26.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.",
@@ -24,7 +24,7 @@
24
24
  "engines": {
25
25
  "node": ">=22.11.0"
26
26
  },
27
- "packageManager": "npm@11.19.0",
27
+ "packageManager": "npm@12.2.0",
28
28
  "type": "module",
29
29
  "bin": {
30
30
  "aligndev": "bin/aligndev.mjs"
@@ -38,9 +38,9 @@
38
38
  "access": "public"
39
39
  },
40
40
  "devDependencies": {
41
- "@types/node": "~24.13.3",
41
+ "@types/node": "~26.6.5",
42
42
  "rimraf": "~6.1.3",
43
43
  "typescript": "~7.0.2",
44
- "vitest": "~5.0.1"
44
+ "vitest": "~5.0.5"
45
45
  }
46
46
  }
@@ -13,6 +13,8 @@ Run `{{ALIGNDEV}} code` from the root of the target project, so the agent works
13
13
 
14
14
  {{ALIGNFIRST_SETUP}}
15
15
 
16
+ Each ticketed run writes `.plans/<ticket>/_aligndev/<stamp>.md`. This file is the durable record of the run. It may live in the project's companion directory; the `sessionFile:` line of `{{ALIGNDEV}} code status` gives the actual path. Its frontmatter carries `status` (`running` → `succeeded`/`failed`) and the `sessionId`, and the `---- Result ----` block holds the outcome. A run that answers more than once lists each response oldest first, separated by `---- Later result ----`. A substantive report may precede a short later acknowledgement; report the substantive outcome.
17
+
16
18
  {{#openclaw}}
17
19
  ## How it runs
18
20
 
@@ -35,8 +37,6 @@ Under OpenClaw, background it through the `exec` tool:
35
37
 
36
38
  As soon as the run is backgrounded, tell the user — in the user's language — that the agent is now working in the background and that you will report back when it finishes (e.g. *"The agent is running in the background — I'll let you know as soon as it's done."*). Post it even when the user asked to be notified only at completion: this line is the promise of exactly that, not an interruption — a launch with no acknowledgement reads as a session gone silent. The acknowledgement is the plain text that ends the turn on every surface. Only the final message is guaranteed to post, so write nothing and call no tool after it. Do **not** also post it via `message`, and do **not** poll.
37
39
 
38
- Each ticketed run writes `.plans/<ticket>/_aligndev/<stamp>.md`. This file is the durable record of the run. It may live in the project's companion directory; the `sessionFile:` line of `{{ALIGNDEV}} code status` gives the actual path. Its frontmatter carries `status` (`running` → `succeeded`/`failed`) and the `sessionId`, and the `---- Result ----` block holds the outcome.
39
-
40
40
  **One protocol run at a time per workspace 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.
41
41
 
42
42
  ## After a background run completes
@@ -68,7 +68,7 @@ If the frontmatter's `exitReason` is `auth_required`, the coding agent is not au
68
68
 
69
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
- 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.
71
+ Choose the launch facility from your **parent host**, independently of the selected child `{{AGENT}}`. The selected profile chooses the child only. All three children (Claude Code, Codex, Pi) remain available from any supported parent.
72
72
 
73
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
 
@@ -107,7 +107,7 @@ Cancel through `background` with `{"action":"stop","id":"<returned-job-id>"}`. I
107
107
 
108
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.
109
109
 
110
- Pi uses ordinary OS permissions and saved project trust, not an implied sandbox. `code.skipPermissions` does not elevate Pi or force project approval.
110
+ Pi uses ordinary OS permissions and saved project trust, not an implied sandbox. `profile.skipPermissions` does not elevate Pi or force project approval.
111
111
 
112
112
  ### Claude Code parent
113
113
 
@@ -143,7 +143,7 @@ Don't reconstruct what happened: no re-running the agent, no `git` archaeology t
143
143
  {{ALIGNDEV}} code resume <sessionId> --message-file <path> --quiet --meta <unique-run-key>
144
144
  {{ALIGNDEV}} code status (<session-file> | --ticket <id> | --no-ticket | --meta <key>) [--result]
145
145
  {{/codingAgent}}
146
- {{ALIGNDEV}} code quota
146
+ {{ALIGNDEV}} code quota [--profile <name>]
147
147
  ```
148
148
 
149
149
  | Command | Description |
@@ -152,15 +152,16 @@ Don't reconstruct what happened: no re-running the agent, no `git` archaeology t
152
152
  | `resume <sessionId>` | Continue an existing session. |
153
153
  {{#openclaw}}
154
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. |
155
- | `quota` | Show the selected coding agent's account limits and reset times. Takes no option. |
155
+ | `quota` | Show the profile's native quota source and account limits. Accepts `--profile`; independent of the coding child. |
156
156
  {{/openclaw}}
157
157
  {{#codingAgent}}
158
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. |
159
+ | `quota` | Show the profile's native quota source and account limits. Accepts `--profile`; independent of the coding child. |
160
160
  {{/codingAgent}}
161
161
 
162
162
  | Option | Description |
163
163
  |--------|-------------|
164
+ | `--profile <name>` | Select a complete named profile for new/resume/quota or agent-specific help; also accepted by `guide code`. Rejected on status. |
164
165
  | `--protocol <p>` | One of `spec`, `plan`, `aad`, `description`, `review`, `merge`. Optional. |
165
166
  | `--ticket <id>` | Ticket ID. With `status`, selects that ticket's newest run. `new --protocol` requires it, or `--no-ticket`. |
166
167
  | `--no-ticket` | With `status`, selects the newest run outside a ticket. With `new --protocol`, `{{ALIGNDEV}} code` reserves the next side ticket through `{{ALIGNFIRST}} ticket --side` and passes it to the agent. The reserved id is in the session file's path and `ticket:` frontmatter; pass it as `--ticket side-N` in later runs. |
@@ -178,16 +179,36 @@ Don't reconstruct what happened: no re-running the agent, no `git` archaeology t
178
179
  {{/codingAgent}}
179
180
 
180
181
  {{#openclaw}}
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.
182
+ The current coding agent is `{{AGENT}}`, profile `{{PROFILE}}`. The profile's nonempty `models` replaces its displayed allowlist. Codex aliases `astra`, `sol`, `terra`, and `luna` resolve to the newest bundled matching slug only when selected; a configured full slug passes through unchanged.
182
183
 
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
+ `{{ALIGNDEV}} code status` checks that a `running` process still owns its recorded pid. A dead run is sealed as `status: failed`, `exitReason: terminated` before the command reports it. `{{ALIGNDEV}} code quota` works without a `.plans` directory and does not start a coding session. Its output belongs to the selected native quota CLI's account; account pairing with the coding child is not verified.
184
185
  {{/openclaw}}
185
186
  {{#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
+ The current coding agent is `{{AGENT}}`, profile `{{PROFILE}}`. A nonempty profile `models` list replaces its accepted model list. Pi has no finite allowlist by default: native selectors pass through unchanged, preferably `provider/model`, with optional thinking suffix. For a Pi child without `--model`, a new run uses profile `defaultModel`, else Pi's own default; a resume retains and validates its recorded model. Codex aliases `astra`, `sol`, `terra`, and `luna` resolve to the newest bundled matching slug only when selected; a configured full slug passes through unchanged.
187
188
 
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
+ `{{ALIGNDEV}} code status` checks that a `running` process still owns its recorded pid. A dead run is sealed as `status: failed`, `exitReason: terminated` before the command reports it. `{{ALIGNDEV}} code quota` needs no `.plans` and starts no session. Its output belongs to the selected native quota CLI's account; account pairing with the coding child is not verified.
189
190
  {{/codingAgent}}
190
191
 
192
+ ### Profiles and resume
193
+
194
+ Effective profile: `{{PROFILE}}`; agent: `{{AGENT}}`; native configuration: `{{NATIVE_CONFIG}}`. Environment values are omitted. Login must use the same effective environment as the child: apply profile `unset/env/configDir`, including HOME, PATH and credential routing, from the same working directory. A bare login in another shell may use a different account.
195
+
196
+ New-session, help, guide and quota selection: explicit `--profile` → project's registry selection → global `code.profile` → automatic resolution. Resume inserts the latest run's recorded named profile before the global selection. A missing selected profile is an error; profiles never merge. Named choices bypass parent detection. Help, guide and quota use the actual cwd and require neither Git nor `.plans`.
197
+
198
+ Automatic resolution uses a sole profile matching the detected agent, or that agent's unique `default: true` among several profiles. Omitted and false flags are equivalent; at most one true flag per agent is allowed. With no matching profile, use that agent's built-ins. A profile for another agent never overrides the detected parent. Without a detected parent, only a sole total profile is inferred; several detected kinds require a named choice. A per-agent flag never chooses the agent kind.
199
+
200
+ Historical resumes with a null or missing profile use detected built-ins unless an explicit, project or global named choice replaces them. They ignore profile counts and flags, still require one detected parent and keep null in the new record. Original transcripts remain unchanged. A deleted recorded name requires an explicit or project replacement; global settings and inference cannot rescue it.
201
+
202
+ Profiles select native configuration/authentication through `configDir` or the corresponding effective environment variable: `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, or `PI_CODING_AGENT_DIR`. `~/` uses the configured home; relative paths use the settings directory. Authenticate in this selected native configuration, not a different account. `env` values are literal non-secret configuration; `unset` removes inherited variables. Credentials remain in native stores or provisioned process environments. Parent identities are stripped after these overrides. Environment values are never recorded in session metadata.
203
+
204
+ Select a user-facing model name, validate it against the accepted names, expand one `modelAliases` mapping, then apply native handling. Without a nonempty `models` override, Claude/Codex add alias names to their native default names; Pi accepts any nonblank selector. Pi exact provider-qualified IDs pin models; fuzzy selectors and thinking suffixes pass through to Pi. Use separate Pi profiles for Codex-backed and Anthropic-backed choices; AlignDev never guesses providers or accounts. Omitted quota uses a native Claude/Codex profile's environment; Pi needs explicit `quota.source: "codex"` or `"claude"`. `"none"` disables quota. Explicit quota starts from the caller environment, applies only quota `unset/env/configDir` and strips parent identities. It never copies coding-profile overrides or Pi credentials. Set quota `configDir` for the intended native account; omission deliberately keeps inherited/default storage. Quota paths follow profile expansion rules. Do not infer account pairing from model selection or retry against a different account after failure.
205
+
206
+ Resume keeps the latest user-facing model unless `--model` replaces it; new-session defaults are ignored. A retained name disallowed by the selected profile requires an explicit accepted replacement. Null keeps the native conversation model. Retained aliases use current mappings, which can change their native targets. Resume requires the same agent and native identity; Pi also requires its recorded real directory. An unavailable conversation fails under the selected account with no fallback, copying or replacement conversation. Run metadata records the effective profile (or null), agent, model name, native ID and cwd. Historical records stay readable; status does not validate launch profiles.
207
+
208
+ Unknown or obsolete settings keys are ignored with value-free warnings on stderr at each fixed settings/profile/quota shape; profile, environment and alias dictionaries remain maps. Recognized invalid values and duplicate defaults still fail. Settings are never rewritten.
209
+
210
+ Direct launch keys and `code.defaultProfiles` are retired and ignored; they supply no legacy behavior. Move launch keys into `code.profiles.<name>`. Move needed per-agent preferences onto matching profiles as `default: true`, omitting singleton flags, and remove the map. Keep profile names unchanged; no automatic conversion occurs. Unique-profile inference can now select configured storage, model, environment and permission settings for new runs that previously used built-ins. Historical null-profile resumes retain their built-in fallback.
211
+
191
212
  `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.
192
213
 
193
214
  {{ALIGNFIRST_USE}}