@aiwg/cli 2026.11.1 → 2026.11.3

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 (120) hide show
  1. package/agentic/code/addons/aiwg-hooks/canonical/aiwg-prompt-discovery.yaml +9 -0
  2. package/agentic/code/addons/aiwg-hooks/hooks/aiwg-prompt-discovery.cjs +136 -0
  3. package/agentic/code/providers/capability-matrix.yaml +2 -2
  4. package/agentic/code/providers/model-capabilities.v1.json +44 -39
  5. package/agentic/code/providers/model-catalog.v1.json +3 -3
  6. package/dist/src/artifacts/cli.js +10 -11
  7. package/dist/src/artifacts/discover-cli-help.js +25 -0
  8. package/dist/src/artifacts/discover-session-facets.js +2 -1
  9. package/dist/src/artifacts/fortemi-core-prebuilt-freshness.js +28 -0
  10. package/dist/src/artifacts/fortemi-core-sync.js +3 -0
  11. package/dist/src/artifacts/framework-capabilities.js +4 -0
  12. package/dist/src/artifacts/framework-source-digest.js +1 -1
  13. package/dist/src/artifacts/index-builder.js +10 -10
  14. package/dist/src/artifacts/index-dependencies.js +72 -0
  15. package/dist/src/artifacts/query-engine-discover-output.js +13 -5
  16. package/dist/src/artifacts/query-engine-discover.js +49 -21
  17. package/dist/src/artifacts/query-engine-entries.js +56 -2
  18. package/dist/src/artifacts/query-engine-options.js +14 -1
  19. package/dist/src/artifacts/query-engine-scoring.js +8 -4
  20. package/dist/src/artifacts/query-engine-show-card.js +2 -0
  21. package/dist/src/artifacts/query-engine-show-load.js +1 -1
  22. package/dist/src/artifacts/query-engine-show.js +3 -1
  23. package/dist/src/artifacts/query-engine-templates.js +33 -0
  24. package/dist/src/artifacts/query-engine-verbose.js +25 -0
  25. package/dist/src/artifacts/relations-builder.js +49 -4
  26. package/dist/src/artifacts/relations.js +9 -0
  27. package/dist/src/artifacts/template-references.js +42 -0
  28. package/dist/src/artifacts/types.js +1 -1
  29. package/dist/src/cli/handlers/bundle-reconciliation.js +7 -3
  30. package/dist/src/cli/handlers/checkpoint-handoff.js +48 -0
  31. package/dist/src/cli/handlers/checkpoint-record.js +20 -0
  32. package/dist/src/cli/handlers/checkpoint.js +50 -17
  33. package/dist/src/cli/handlers/dataset.js +17 -0
  34. package/dist/src/cli/handlers/decision.js +1 -1
  35. package/dist/src/cli/handlers/doctor-args.js +3 -1
  36. package/dist/src/cli/handlers/doctor-help.js +2 -1
  37. package/dist/src/cli/handlers/help.js +1 -1
  38. package/dist/src/cli/handlers/refresh-bundles.js +2 -1
  39. package/dist/src/cli/handlers/refresh-managed-deployment.js +196 -0
  40. package/dist/src/cli/handlers/refresh.js +10 -2
  41. package/dist/src/cli/handlers/subcommands-discovery.js +8 -1
  42. package/dist/src/cli/handlers/use.js +26 -5
  43. package/dist/src/cli/services/deployment-verification.js +11 -7
  44. package/dist/src/config/decision-config.js +2 -1
  45. package/dist/src/config/jev-credential-reference.js +56 -0
  46. package/dist/src/config/user-config.js +13 -19
  47. package/dist/src/config/worker-write.js +4 -10
  48. package/dist/src/decision/ask.js +3 -2
  49. package/dist/src/decision/jev-credentials.js +22 -0
  50. package/dist/src/decision/ledger.js +15 -15
  51. package/dist/src/decision/offload.js +7 -8
  52. package/dist/src/decision/openbao-kv-resolver.mjs +96 -0
  53. package/dist/src/decision/openbao-runtime.js +101 -0
  54. package/dist/src/delivery/pr.js +2 -0
  55. package/dist/src/delivery/template-sections.js +56 -0
  56. package/dist/src/extensions/claude-hooks-installer.js +61 -53
  57. package/dist/src/extensions/managed-hook-script-state.js +48 -0
  58. package/dist/src/extensions/muse-managed-hooks.js +49 -0
  59. package/dist/src/issues/cli.js +3 -0
  60. package/dist/src/issues/external-cli.js +4 -1
  61. package/dist/src/issues/live.js +9 -2
  62. package/dist/src/issues/local.js +5 -1
  63. package/dist/src/issues/tracker-policy.js +11 -1
  64. package/dist/src/mcp/json-document.d.mts +2 -0
  65. package/dist/src/models/model-capabilities.v1.json +44 -39
  66. package/dist/src/models/model-catalog.v1.json +3 -3
  67. package/dist/src/models/provider-policy.js +8 -0
  68. package/dist/src/models/worker-health-readiness.js +20 -4
  69. package/dist/src/models/worker-health-snapshot.js +29 -0
  70. package/dist/src/models/worker-installation.d.mts +5 -1
  71. package/dist/src/models/worker-installation.mjs +11 -5
  72. package/dist/src/models/worker-qualification-policy.js +54 -0
  73. package/dist/src/providers/capability-matrix.yaml +2 -2
  74. package/dist/src/providers/skill-ownership.d.mts +1 -0
  75. package/dist/src/providers/transformation-receipt-integration.js +4 -2
  76. package/dist/src/providers/transformation-receipt.js +4 -2
  77. package/dist/src/serve/worker-invocation.js +4 -2
  78. package/dist/src/smiths/context-pipeline/workspace-audit.js +34 -17
  79. package/dist/src/smiths/context-pipeline/workspace-context-shared.js +12 -6
  80. package/dist/src/smiths/context-pipeline/workspace-doctor.js +48 -4
  81. package/dist/src/smiths/context-pipeline/workspace-document.js +5 -2
  82. package/dist/src/smiths/context-pipeline/workspace-migration.js +2 -1
  83. package/dist/src/smiths/hook-bridge/codex-translator.js +150 -94
  84. package/dist/src/smiths/hook-bridge/codex-trust.js +50 -0
  85. package/dist/src/smiths/hook-bridge/factory-hook-config.js +132 -0
  86. package/dist/src/smiths/hook-bridge/factory-translator.js +88 -33
  87. package/dist/src/smiths/hook-bridge/factory-trust.js +56 -0
  88. package/dist/src/smiths/hook-bridge/index.js +3 -3
  89. package/dist/src/smiths/hook-bridge/loader.js +10 -2
  90. package/dist/src/smiths/hook-bridge/prompt-discovery-gaps.js +0 -1
  91. package/dist/src/storage/workspace-permissions-health.js +64 -0
  92. package/dist/src/storage/workspace-permissions.js +51 -0
  93. package/package.json +6 -1
  94. package/tools/agents/providers/base-files.mjs +2 -1
  95. package/tools/agents/providers/base-flat-artifacts.mjs +6 -3
  96. package/tools/agents/providers/base-models-platforms.mjs +3 -3
  97. package/tools/agents/providers/base-skill-copy.mjs +2 -0
  98. package/tools/agents/providers/bound-rules-pointer.mjs +21 -0
  99. package/tools/agents/providers/claude-post-deploy.mjs +9 -5
  100. package/tools/agents/providers/codex-post-deploy.mjs +10 -0
  101. package/tools/agents/providers/factory-hooks.mjs +43 -0
  102. package/tools/agents/providers/factory.mjs +4 -91
  103. package/tools/agents/providers/muse-hooks.mjs +4 -43
  104. package/tools/agents/providers/muse-prompt-discovery.mjs +3 -7
  105. package/tools/agents/providers/packaged-codex-agents.mjs +48 -0
  106. package/tools/agents/providers/rule-delivery-surface.mjs +4 -4
  107. package/tools/agents/providers/rule-presentation.mjs +6 -5
  108. package/tools/agents/providers/rule-projection.mjs +10 -2
  109. package/tools/agents/providers/rule-startup.mjs +8 -1
  110. package/tools/cli/decision-offload-report.mjs +9 -2
  111. package/tools/plugin/issue-template-copies.mjs +24 -0
  112. package/tools/plugin/package-plugins.mjs +17 -4
  113. package/tools/ralph-external/lib/claude-adapter.mjs +2 -2
  114. package/tools/ralph-external/lib/factory-adapter.mjs +7 -8
  115. package/tools/ralph-external/lib/worker-artifacts.mjs +4 -2
  116. package/tools/ralph-external/lib/worker-final.mjs +43 -8
  117. package/tools/ralph-external/lib/worker-launch-cli.mjs +10 -1
  118. package/tools/ralph-external/lib/worker-prompt.mjs +35 -0
  119. package/tools/ralph-external/lib/worker-run-directory-refusal.mjs +8 -0
  120. package/tools/ralph-external/session-launcher.mjs +10 -7
@@ -8,6 +8,7 @@ import { resolveRuleBindingTarget } from './query-engine.js';
8
8
  import { Minimatch } from 'minimatch';
9
9
  import { FRAMEWORK_RELATIONS_REVISION } from './framework-source-digest.js';
10
10
  import { writeIndexFile } from './index-reader.js';
11
+ import { createDependencyResolver } from './index-dependencies.js';
11
12
  import { RELATIONS_SCHEMA, RELATIONS_VERSION, RULE_TIERS, emptyRuleStats, } from './relations.js';
12
13
  const TARGET_TYPES = new Set(['skill', 'agent', 'flow', 'command']);
13
14
  const BINDING_TYPES = { skills: 'skill', agents: 'agent', flows: 'flow' };
@@ -28,9 +29,9 @@ function owner(entry) {
28
29
  const kind = { frameworks: 'framework', addons: 'addon', extensions: 'extension' }[match[1]];
29
30
  return { id: `${kind}:${match[2]}`, kind };
30
31
  }
31
- /** Only rule/action sources affect this projection; no full metadata serialization or file rereads. */
32
+ /** Only rule/action/template sources affect this projection; no file rereads. */
32
33
  export function relationsFingerprint(entries) {
33
- const sources = entries.filter(entry => TARGET_TYPES.has(entry.type) || ['rule', 'behavior'].includes(entry.type))
34
+ const sources = entries.filter(entry => TARGET_TYPES.has(entry.type) || ['rule', 'behavior', 'template'].includes(entry.type))
34
35
  .map(entry => [entry.path, entry.checksum]).sort((a, b) => a[0].localeCompare(b[0]));
35
36
  return { version: RELATIONS_VERSION, sources: `sha256:${createHash('sha256').update(JSON.stringify({ projectionVersion: FRAMEWORK_RELATIONS_REVISION, extractorVersion: INDEX_EXTRACTOR_VERSION, sources })).digest('hex')}` };
36
37
  }
@@ -50,10 +51,10 @@ function statsFor(ids, index) {
50
51
  export function buildRelations(entries) {
51
52
  const index = {
52
53
  $schema: RELATIONS_SCHEMA, version: RELATIONS_VERSION, generatedAt: '1970-01-01T00:00:00.000Z',
53
- fingerprint: relationsFingerprint(entries), artifacts: {}, rules: {}, targets: {}, capabilities: {}, aliases: { targets: {}, rules: {} },
54
+ fingerprint: relationsFingerprint(entries), artifacts: {}, rules: {}, templates: {}, targets: {}, capabilities: {}, aliases: { targets: {}, rules: {}, templates: {} },
54
55
  };
55
56
  for (const entry of [...entries].sort((a, b) => a.path.localeCompare(b.path))) {
56
- if (!TARGET_TYPES.has(entry.type) && !['rule', 'behavior'].includes(entry.type))
57
+ if (!TARGET_TYPES.has(entry.type) && !['rule', 'behavior', 'template'].includes(entry.type))
57
58
  continue;
58
59
  const { path: sourcePath, type, name, title, kernel, script, governedPaths } = entry;
59
60
  index.artifacts[relationId(entry)] = { path: sourcePath, type, title, ...(name ? { name } : {}), ...(kernel ? { kernel } : {}), ...(script ? { script } : {}), ...(governedPaths ? { governedPaths } : {}) };
@@ -150,8 +151,52 @@ export function buildRelations(entries) {
150
151
  index.aliases.targets[`skill:projected:${target.name}`] = [key];
151
152
  target.rule_stats = statsFor(target.rules, index);
152
153
  }
154
+ addTemplateRelations(entries, index);
153
155
  return index;
154
156
  }
157
+ /** Project resolved index dependencies, including Markdown-link reverse edges. */
158
+ function addTemplateRelations(entries, index) {
159
+ const byPath = Object.fromEntries(entries.map(entry => [entry.path, entry]));
160
+ const resolve = createDependencyResolver(byPath);
161
+ const templates = entries.filter(entry => entry.type === 'template').sort((a, b) => a.path.localeCompare(b.path));
162
+ const link = (component, template) => {
163
+ if (!TARGET_TYPES.has(component.type))
164
+ return;
165
+ const target = index.targets[`${component.type}:${relationId(component)}`];
166
+ const id = relationId(template);
167
+ const edges = target.templates ??= [];
168
+ if (edges.includes(id))
169
+ return;
170
+ edges.push(id);
171
+ index.templates[id].used_by.push({ type: component.type, id: relationId(component) });
172
+ };
173
+ for (const template of templates) {
174
+ const id = relationId(template);
175
+ index.templates[id] = { name: template.name ?? slug(template), path: template.path, title: template.title, used_by: [] };
176
+ for (const alias of new Set([template.name, slug(template), template.path].filter((value) => !!value))) {
177
+ (index.aliases.templates[alias] ??= []).push(id);
178
+ }
179
+ }
180
+ for (const component of entries.filter(entry => TARGET_TYPES.has(entry.type))) {
181
+ for (const dependency of component.dependencies ?? []) {
182
+ const template = byPath[resolve(component.path, dependency) ?? ''];
183
+ if (template?.type === 'template')
184
+ link(component, template);
185
+ }
186
+ }
187
+ for (const template of templates)
188
+ for (const dependent of template.dependents ?? []) {
189
+ if (byPath[dependent])
190
+ link(byPath[dependent], template);
191
+ }
192
+ for (const target of Object.values(index.targets)) {
193
+ if (target.projected_from)
194
+ target.templates = [...(index.targets[`${target.projected_from.type}:${target.projected_from.id}`].templates ?? [])];
195
+ target.templates?.sort();
196
+ }
197
+ for (const template of Object.values(index.templates))
198
+ template.used_by.sort((a, b) => `${a.type}:${a.id}`.localeCompare(`${b.type}:${b.id}`));
199
+ }
155
200
  export async function writeRelations(entries, cwd, indexDir, force = false, existingDir = indexDir) {
156
201
  const values = Object.values(entries);
157
202
  const fingerprint = relationsFingerprint(values);
@@ -25,6 +25,15 @@ export class RelationsReader {
25
25
  this.index = index;
26
26
  this.pinnedRuleIds = pinnedRuleIds;
27
27
  }
28
+ templatesForTarget(type, id) {
29
+ const key = `${type}:${id}`;
30
+ const resolved = Object.hasOwn(this.index.targets, key) ? key : lookupAlias(this.index.aliases.targets, key);
31
+ return [...(resolved ? this.index.targets[resolved]?.templates ?? [] : [])];
32
+ }
33
+ targetsForTemplate(id) {
34
+ const resolved = Object.hasOwn(this.index.templates ?? {}, id) ? id : lookupAlias(this.index.aliases.templates ?? {}, id);
35
+ return resolved ? (this.index.templates?.[resolved]?.used_by ?? []).map(target => ({ ...target })) : [];
36
+ }
28
37
  rulesForTarget(type, id) {
29
38
  const key = `${type}:${id}`;
30
39
  const resolved = Object.hasOwn(this.index.targets, key) ? key : lookupAlias(this.index.aliases.targets, key);
@@ -0,0 +1,42 @@
1
+ // Extract concrete template paths and resolve them within their owning bundle.
2
+ import path from 'node:path';
3
+ export function isTemplateReference(value) {
4
+ return /(?:^|\/)templates\//.test(value) && /\.[\w-]+$/.test(value);
5
+ }
6
+ export function extractTemplateReferences(content) {
7
+ const references = new Set();
8
+ // Scan whole tokens once: do not restart an unanchored path regex at every
9
+ // character of a long non-matching path. Code samples also contain references.
10
+ for (const match of content.matchAll(/[^\s`"'()[\]{},;:<>|\\]+/g)) {
11
+ const token = match[0].replace(/^@/, '').replace(/[.!?]+$/, '').split('#')[0];
12
+ if (!/^(?:\$AIWG_ROOT\/|\.{1,2}\/|[\w-])/.test(token))
13
+ continue;
14
+ if (!/^[\w$./-]+$/.test(token) || !isTemplateReference(token))
15
+ continue;
16
+ references.add(token);
17
+ }
18
+ return [...references];
19
+ }
20
+ export function sourceBundleRoot(sourcePath) {
21
+ return sourcePath.replace(/\\/g, '/').match(/^(.*?(?:agentic\/code|\.aiwg)\/(?:addons|frameworks|extensions)\/[^/]+)\//)?.[1];
22
+ }
23
+ /** Ordered repo-relative candidates, shared by graph resolution and linting. */
24
+ export function templateReferenceCandidates(sourcePath, reference) {
25
+ const target = reference.replace(/^@/, '');
26
+ if (target.startsWith('$AIWG_ROOT/'))
27
+ return [path.posix.normalize(target.slice(11))];
28
+ if (target.startsWith('agentic/'))
29
+ return [path.posix.normalize(target)];
30
+ if (target.startsWith('./') || target.startsWith('../')) {
31
+ return [path.posix.normalize(path.posix.join(path.posix.dirname(sourcePath), target))];
32
+ }
33
+ const bundle = sourceBundleRoot(sourcePath);
34
+ if (target.startsWith('templates/'))
35
+ return bundle ? [`${bundle}/${target}`] : [target];
36
+ // Explicit <bundle>/templates/... shorthand may name a sibling bundle.
37
+ if (/^[\w-]+\/(?:[\w-]+\/)*templates\//.test(target)) {
38
+ return ['frameworks', 'addons', 'extensions'].map(group => `agentic/code/${group}/${target}`);
39
+ }
40
+ return [path.posix.normalize(path.posix.join(path.posix.dirname(sourcePath), target))];
41
+ }
42
+ //# sourceMappingURL=template-references.js.map
@@ -110,7 +110,7 @@ export const INDEX_VERSION = '1.0.0';
110
110
  * making the serialized index schema incompatible; a mismatch simply forces a
111
111
  * one-time content re-extraction during the next incremental build.
112
112
  */
113
- export const INDEX_EXTRACTOR_VERSION = '2026.10.24.1';
113
+ export const INDEX_EXTRACTOR_VERSION = '2026.11.06.1';
114
114
  /**
115
115
  * Built-in graph definitions
116
116
  */
@@ -16,6 +16,10 @@ export function bundleProviders(installed, id, requested) {
16
16
  const entry = Object.entries(installed).find(([key]) => frameworkRegistryId(key) === frameworkRegistryId(id))?.[1];
17
17
  return Object.keys(entry?.deployedTo ?? {}).filter(provider => !requested || requested.split(',').includes(provider));
18
18
  }
19
+ function hasLegacyAllSelection(config, provider) {
20
+ const flags = config.installed.all?.deployedTo[provider];
21
+ return provider !== 'flue' && flags !== undefined && flags.skipUtils === undefined && flags.kernelOnly === undefined;
22
+ }
19
23
  export async function expectedBundleOwners(config, provider, frameworkRoot) {
20
24
  const selected = Object.keys(config.installed).filter(id => bundleProviders(config.installed, id, provider).length);
21
25
  const expected = new Set(selected.map(frameworkRegistryId));
@@ -25,7 +29,7 @@ export async function expectedBundleOwners(config, provider, frameworkRoot) {
25
29
  continue;
26
30
  const flags = config.installed[id].deployedTo[provider];
27
31
  if (id === 'all' && provider !== 'flue' && (flags.skipUtils !== undefined || flags.kernelOnly !== undefined)) {
28
- expected.delete('all');
32
+ // The composed pass owns outputs as `all`; expanding its scope must retain that owner.
29
33
  for (const name of fs.readdirSync(path.join(frameworkRoot, 'agentic/code/frameworks'))) {
30
34
  if (fs.existsSync(path.join(frameworkRoot, 'agentic/code/frameworks', name, 'manifest.json')))
31
35
  expected.add(frameworkRegistryId(name));
@@ -104,7 +108,7 @@ export async function pruneUndeclaredBundles(project, config, requested, dryRun
104
108
  continue;
105
109
  const selected = expected.get(provider);
106
110
  for (const owner of receiptOwners(project, provider)) {
107
- if (hashPruned.has(`${provider}:${owner}`) || (selected.has('all') && provider !== 'flue') || selected.has(frameworkRegistryId(owner)))
111
+ if (hashPruned.has(`${provider}:${owner}`) || hasLegacyAllSelection(config, provider) || selected.has(frameworkRegistryId(owner)))
108
112
  continue;
109
113
  const implicit = !history[provider]?.[frameworkRegistryId(owner)] && Object.values(history[provider] ?? {}).some(entry => entry.produces?.includes(frameworkRegistryId(owner)) || entry.produces?.includes('*'));
110
114
  if (implicit)
@@ -114,7 +118,7 @@ export async function pruneUndeclaredBundles(project, config, requested, dryRun
114
118
  continue;
115
119
  }
116
120
  const otherProviders = [...expected].filter(([other, owners]) => other !== provider
117
- && (history[other]?.[frameworkRegistryId(owner)]?.copy || history[other]?.[frameworkRegistryId(owner)]?.package || owners.has(frameworkRegistryId(owner)) || other !== 'flue' && owners.has('all'))).map(([other]) => other);
121
+ && (history[other]?.[frameworkRegistryId(owner)]?.copy || history[other]?.[frameworkRegistryId(owner)]?.package || owners.has(frameworkRegistryId(owner)) || hasLegacyAllSelection(config, other))).map(([other]) => other);
118
122
  const sharedRoots = deployedSkillRoots(project, provider).filter(root => otherProviders.some(other => deployedSkillRoots(project, other).includes(root)));
119
123
  console.log(`${dryRun ? 'Would remove' : 'Removing'} ${bundleUseName(owner)} for ${provider}`);
120
124
  // A temporary historical record supplies context for the public per-bundle
@@ -0,0 +1,48 @@
1
+ // Render shipped session handoff documents and persist them beside their checkpoint record.
2
+ import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
3
+ import { join } from 'node:path';
4
+ import { assertCheckpointRecord } from './checkpoint-record.js';
5
+ export async function writeCheckpointHandoff(frameworkRoot, checkpointsDir, record, input) {
6
+ const template = await readFile(join(frameworkRoot, 'agentic/code/addons/aiwg-utils/templates/checkpoint-handoff.md'), 'utf8');
7
+ const dir = join(checkpointsDir, record.id);
8
+ record.handoffPath = join(dir, 'handoff.md');
9
+ record.nextSessionPromptPath = join(dir, 'next-session-prompt.md');
10
+ assertCheckpointRecord(record, join(record.id, 'checkpoint.json'));
11
+ const fields = {
12
+ scope: input.scope ?? '[TODO: Define scope and ownership.]',
13
+ state: [
14
+ `Checkpoint: ${record.id}${record.name ? ` (${record.name})` : ''}`,
15
+ `Created: ${record.createdAt}`,
16
+ `Working directory: ${record.cwd}`,
17
+ `Phase: ${record.phase ?? '[TODO: Record current phase.]'}`,
18
+ `Step: ${record.step ?? '[TODO: Record current step.]'}`,
19
+ ...(record.gitHead ? [`Git HEAD: ${record.gitHead}`] : []),
20
+ record.note ?? '[TODO: Describe completed work, verification, and outstanding state.]',
21
+ ].join('\n\n'),
22
+ todos: input.todos.length ? input.todos.map((todo, i) => `${i + 1}. ${todo}`).join('\n')
23
+ : '1. [TODO: List remaining work in execution order.]',
24
+ constraints: input.constraints.length ? input.constraints.map(item => `- ${item}`).join('\n')
25
+ : '- [TODO: Record binding constraints.]',
26
+ links: record.artifacts.length ? record.artifacts.map(path => `- ${path}`).join('\n')
27
+ : '- [TODO: Link relevant artifacts and references.]',
28
+ };
29
+ const handoff = template.replace(/\{\{(\w+)\}\}/g, (match, key) => fields[key] ?? match);
30
+ const prompt = [
31
+ `Continue checkpoint ${record.id}${record.name ? ` (${record.name})` : ''} in ${record.cwd}.`,
32
+ 'Read WORKSPACE.md and AIWG.md if present, then read the handoff:',
33
+ record.handoffPath,
34
+ 'Follow its binding constraints and ordered to-do list. Verify current state before continuing.',
35
+ '',
36
+ ].join('\n');
37
+ await mkdir(dir);
38
+ try {
39
+ await writeFile(record.handoffPath, handoff, { flag: 'wx' });
40
+ await writeFile(record.nextSessionPromptPath, prompt, { flag: 'wx' });
41
+ await writeFile(join(dir, 'checkpoint.json'), `${JSON.stringify(record, null, 2)}\n`, { flag: 'wx' });
42
+ }
43
+ catch (error) {
44
+ await rm(dir, { recursive: true, force: true });
45
+ throw error;
46
+ }
47
+ }
48
+ //# sourceMappingURL=checkpoint-handoff.js.map
@@ -0,0 +1,20 @@
1
+ // Validate CLI checkpoint records against their canonical catalog contract at persistence boundaries.
2
+ import { loadSchemaCatalog, SchemaResolver, SchemaValidator } from '../../schema/index.js';
3
+ import { findPackageRoot } from '../find-package-root.js';
4
+ export const CHECKPOINT_SCHEMA_ID = 'https://aiwg.io/schemas/artifacts/checkpoint-record.v1.schema.json';
5
+ let validator;
6
+ export function assertCheckpointRecord(value, source) {
7
+ if (!validator) {
8
+ const rootDir = findPackageRoot(import.meta.dirname);
9
+ if (!rootDir)
10
+ throw new Error('Cannot locate checkpoint schema package root');
11
+ const loaded = loadSchemaCatalog({ rootDir });
12
+ if (!loaded.valid || !loaded.catalog)
13
+ throw new Error('Invalid checkpoint schema catalog');
14
+ validator = new SchemaValidator(new SchemaResolver(loaded.catalog, { rootDir }), { rootDir });
15
+ }
16
+ if (!validator.validate(CHECKPOINT_SCHEMA_ID, value).valid) {
17
+ throw new Error(`Invalid checkpoint record: ${source}`);
18
+ }
19
+ }
20
+ //# sourceMappingURL=checkpoint-record.js.map
@@ -4,16 +4,22 @@ import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
4
4
  import { join } from 'node:path';
5
5
  import { boundedExecFileSync } from '../../process/bounded-child-process.mjs';
6
6
  import { resolveProjectAiwgDirForWrite } from '../../config/project-artifacts.js';
7
+ import { writeCheckpointHandoff } from './checkpoint-handoff.js';
8
+ import { assertCheckpointRecord } from './checkpoint-record.js';
7
9
  const usage = [
8
10
  'aiwg checkpoint — Save or inspect a workflow resume position',
9
11
  '',
10
12
  'Usage:',
11
13
  ' aiwg checkpoint create [--name N] [--phase P] [--step S] [--artifact <path>]... [--note N]',
14
+ ' [--handoff [--scope S] [--todo T]... [--constraint C]...]',
12
15
  ' aiwg checkpoint list [--json]',
13
16
  ' aiwg checkpoint recover [<id|name>] [--json]',
14
17
  '',
15
18
  'Recover reports the saved record without changing the repository.',
16
19
  'Duplicate names select the newest matching checkpoint.',
20
+ 'Handoffs include handoff.md and next-session-prompt.md; omitted sections have TODO placeholders.',
21
+ 'Create is headless. Value flags require nonempty values; --scope/--todo/--constraint require --handoff.',
22
+ 'Recover prints the saved prompt and both paths for handoffs; --json returns the record.',
17
23
  ].join('\n');
18
24
  function parse(args) {
19
25
  const [action, ...rest] = args;
@@ -21,6 +27,10 @@ function parse(args) {
21
27
  throw new Error(`Unknown checkpoint action: ${action ?? '(missing)'}\n${usage}`);
22
28
  const values = {};
23
29
  const artifacts = [];
30
+ const todos = [];
31
+ const constraints = [];
32
+ let scope;
33
+ let handoff = false;
24
34
  let lookup;
25
35
  let json = false;
26
36
  for (let i = 0; i < rest.length; i++) {
@@ -29,14 +39,29 @@ function parse(args) {
29
39
  json = true;
30
40
  continue;
31
41
  }
32
- if (action === 'create' && /^--(name|phase|step|artifact|note)(=|$)/.test(arg)) {
42
+ if (arg === '--handoff' && action === 'create') {
43
+ if (handoff)
44
+ throw new Error('--handoff may be given once');
45
+ handoff = true;
46
+ continue;
47
+ }
48
+ if (action === 'create' && /^--(name|phase|step|artifact|note|scope|todo|constraint)(=|$)/.test(arg)) {
33
49
  const eq = arg.indexOf('=');
34
50
  const key = arg.slice(2, eq < 0 ? undefined : eq);
35
51
  const value = eq < 0 ? rest[++i] : arg.slice(eq + 1);
36
- if (!value || (eq < 0 && value.startsWith('-')))
52
+ if (!value?.trim() || (eq < 0 && value.startsWith('-')))
37
53
  throw new Error(`--${key} requires a value`);
38
54
  if (key === 'artifact')
39
55
  artifacts.push(value);
56
+ else if (key === 'todo')
57
+ todos.push(value);
58
+ else if (key === 'constraint')
59
+ constraints.push(value);
60
+ else if (key === 'scope') {
61
+ if (scope !== undefined)
62
+ throw new Error('--scope may be given once');
63
+ scope = value;
64
+ }
40
65
  else {
41
66
  if (key in values)
42
67
  throw new Error(`--${key} may be given once`);
@@ -49,12 +74,16 @@ function parse(args) {
49
74
  else
50
75
  throw new Error(`Unexpected checkpoint argument: ${arg}`);
51
76
  }
52
- return { action, values, artifacts, lookup, json };
77
+ if (!handoff && (scope !== undefined || todos.length || constraints.length)) {
78
+ throw new Error('--scope, --todo, and --constraint require --handoff');
79
+ }
80
+ return { action, values, artifacts, lookup, json, handoff, scope, todos, constraints };
53
81
  }
54
82
  async function records(dir) {
55
83
  let files;
56
84
  try {
57
- files = await readdir(dir);
85
+ files = (await readdir(dir, { withFileTypes: true })).flatMap(entry => entry.isFile() && entry.name.endsWith('.json') ? [entry.name]
86
+ : entry.isDirectory() && entry.name.startsWith('ckpt_') ? [join(entry.name, 'checkpoint.json')] : []);
58
87
  }
59
88
  catch (error) {
60
89
  if (error.code === 'ENOENT')
@@ -63,14 +92,7 @@ async function records(dir) {
63
92
  }
64
93
  const result = await Promise.all(files.filter(file => file.endsWith('.json')).map(async (file) => {
65
94
  const record = JSON.parse(await readFile(join(dir, file), 'utf8'));
66
- if (!record || typeof record.id !== 'string' || typeof record.cwd !== 'string'
67
- || typeof record.createdAt !== 'string' || !Number.isFinite(Date.parse(record.createdAt))
68
- || !Array.isArray(record.artifacts) || !record.artifacts.every(path => typeof path === 'string')
69
- || ['name', 'gitHead', 'phase', 'step', 'note'].some(key => {
70
- const value = record[key];
71
- return value !== undefined && typeof value !== 'string';
72
- }))
73
- throw new Error(`Invalid checkpoint record: ${file}`);
95
+ assertCheckpointRecord(record, file);
74
96
  return record;
75
97
  }));
76
98
  return result.sort((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt) || b.id.localeCompare(a.id));
@@ -90,7 +112,7 @@ function resumeText(record) {
90
112
  export const checkpointHandler = {
91
113
  id: 'checkpoint',
92
114
  name: 'Workflow Checkpoints',
93
- description: 'Create, list, or recover a saved workflow position',
115
+ description: 'Create, list, or recover workflow positions and session handoffs',
94
116
  category: 'workspace',
95
117
  aliases: [],
96
118
  async help() { return { exitCode: 0, message: usage, rawOutput: true }; },
@@ -99,7 +121,7 @@ export const checkpointHandler = {
99
121
  return { exitCode: 0, message: usage, rawOutput: true };
100
122
  }
101
123
  try {
102
- const { action, values, artifacts, lookup, json } = parse(ctx.args);
124
+ const { action, values, artifacts, lookup, json, handoff, scope, todos, constraints } = parse(ctx.args);
103
125
  const dir = join(resolveProjectAiwgDirForWrite(ctx.cwd), 'checkpoints');
104
126
  if (action === 'create') {
105
127
  if (ctx.dryRun)
@@ -115,8 +137,14 @@ export const checkpointHandler = {
115
137
  id: `ckpt_${randomUUID()}`, ...values, createdAt: new Date().toISOString(),
116
138
  cwd: ctx.cwd, ...(gitHead ? { gitHead } : {}), artifacts,
117
139
  };
140
+ assertCheckpointRecord(record, record.id);
118
141
  await mkdir(dir, { recursive: true });
119
- await writeFile(join(dir, `${record.id}.json`), `${JSON.stringify(record, null, 2)}\n`, { flag: 'wx' });
142
+ if (handoff) {
143
+ await writeCheckpointHandoff(ctx.frameworkRoot, dir, record, { scope, todos, constraints });
144
+ }
145
+ else {
146
+ await writeFile(join(dir, `${record.id}.json`), `${JSON.stringify(record, null, 2)}\n`, { flag: 'wx' });
147
+ }
120
148
  return { exitCode: 0, message: record.id, rawOutput: true };
121
149
  }
122
150
  const all = await records(dir);
@@ -124,7 +152,7 @@ export const checkpointHandler = {
124
152
  return {
125
153
  exitCode: 0, rawOutput: true,
126
154
  message: json ? JSON.stringify(all, null, 2) : all.length
127
- ? ['ID\tName\tCreated\tPhase / Step', ...all.map(record => `${record.id}\t${record.name ?? '(unnamed)'}\t${record.createdAt}\t${record.phase ?? '-'} / ${record.step ?? '-'}`)].join('\n')
155
+ ? ['ID\tName\tCreated\tPhase / Step\tHandoff', ...all.map(record => `${record.id}\t${record.name ?? '(unnamed)'}\t${record.createdAt}\t${record.phase ?? '-'} / ${record.step ?? '-'}\t${record.handoffPath ? 'yes' : '-'}`)].join('\n')
128
156
  : 'No checkpoints found.',
129
157
  };
130
158
  }
@@ -132,7 +160,12 @@ export const checkpointHandler = {
132
160
  : all.find(record => record.id === lookup) ?? all.find(record => record.name === lookup);
133
161
  if (!record)
134
162
  throw new Error(lookup === undefined ? 'No checkpoints found.' : `Checkpoint not found: ${lookup}`);
135
- return { exitCode: 0, message: json ? JSON.stringify(record, null, 2) : resumeText(record), rawOutput: true };
163
+ let message = json ? JSON.stringify(record, null, 2) : resumeText(record);
164
+ if (!json && record.handoffPath && record.nextSessionPromptPath) {
165
+ const prompt = await readFile(record.nextSessionPromptPath, 'utf8');
166
+ message += `\nHandoff: ${record.handoffPath}\nNext-session prompt: ${record.nextSessionPromptPath}\n\n${prompt}`;
167
+ }
168
+ return { exitCode: 0, message, rawOutput: true };
136
169
  }
137
170
  catch (error) {
138
171
  return { exitCode: 1, message: error instanceof Error ? error.message : String(error) };
@@ -73,6 +73,22 @@ export async function executeDatasetCommand(ctx, providedService) {
73
73
  exitCode: 1,
74
74
  message: `Unknown dataset action '${action ?? ""}'.`,
75
75
  };
76
+ if (action === "status" && !ids[0])
77
+ return {
78
+ exitCode: 1,
79
+ rawOutput: true,
80
+ message: presentDatasetResult({
81
+ schema: "aiwg.dataset-orchestration/v1",
82
+ action,
83
+ ok: false,
84
+ diagnostics: [{
85
+ code: "DATASET_ARGUMENT_REQUIRED",
86
+ message: "Missing required run ID. Usage: aiwg dataset status <run-id>",
87
+ boundary: "input",
88
+ retryable: false,
89
+ }],
90
+ }, ctx.args.includes("--json")),
91
+ };
76
92
  const s = providedService ?? service(ctx);
77
93
  let result;
78
94
  switch (action) {
@@ -155,6 +171,7 @@ export const datasetHandler = {
155
171
  "source/plan: --file <json>",
156
172
  "preview: <source-id> [--count N] [--offline]",
157
173
  "ingest: <plan-id> --digest <sha256> --idempotency-key <key> [--approve id,id]",
174
+ "status <run-id>: Inspect one run by its required ID.",
158
175
  "All actions: --json for the canonical aiwg.dataset-orchestration/v1 envelope.",
159
176
  ].join("\n"),
160
177
  };
@@ -167,7 +167,7 @@ async function decisionAsk(ctx) {
167
167
  throw invocation.outcome === 'unknown' ? invocation.error : new Error('Decision ask was skipped');
168
168
  const result = invocation.result;
169
169
  if (args.includes('--json'))
170
- return jsonResult(result);
170
+ return jsonResult({ ...result, ledgerRecorded: invocation.opportunity.ledgerRecorded });
171
171
  if (result.status === 'fallback')
172
172
  return { exitCode: 0, message: `FALLBACK to LLM: ${result.reason}`, rawOutput: true };
173
173
  return { exitCode: 0, message: `${String(result.answer)} (confidence ${result.confidence?.toFixed(2) ?? 'unknown'}, ${result.model ?? 'unknown-model'})`, rawOutput: true };
@@ -4,7 +4,7 @@ export function parsePublicDoctorFlags(args) {
4
4
  const valueFlags = ['--provider', '--bundle', '--scope', '--context-baseline', '--context-budget-tokens', '--cli', '--forget-approval', '--group'];
5
5
  const knownFlags = new Set([
6
6
  ...valueFlags, '--list-approvals', '--all-providers', '--probe-workers', '--qualify', '--yes', '--dry-run', '--no-budget-check', '--strict-context', '--json',
7
- '--resources', '--decision-offload', '--deployment', '--user', '--verbose', '-v', '--project-local', '--quiet', '--help', '-h',
7
+ '--resources', '--decision-offload', '--fix', '--deployment', '--user', '--verbose', '-v', '--project-local', '--quiet', '--help', '-h',
8
8
  ]);
9
9
  const hasSwitch = (name) => hasPositionalOrSwitch(args, name, valueFlags);
10
10
  const values = new Map();
@@ -21,6 +21,8 @@ export function parsePublicDoctorFlags(args) {
21
21
  throw new Error(`Unknown flag: ${name}`);
22
22
  }
23
23
  }
24
+ if (hasSwitch('--fix') && !hasSwitch('--decision-offload'))
25
+ throw new Error('--fix requires --decision-offload');
24
26
  if (values.get('--group') !== undefined && !hasSwitch('--resources'))
25
27
  throw new Error('--group requires --resources');
26
28
  if (hasSwitch('--resources') && (['--probe-workers', '--decision-offload', '--deployment', '--user', '--project-local'].some(hasSwitch) || values.get('--scope') !== undefined)) {
@@ -20,7 +20,8 @@ Options:
20
20
  --cli NAME Limit worker probes, qualification, or approvals to one CLI
21
21
  --group <name> Apply the named group cap (requires --resources)
22
22
  --resources Report live host resources, threshold origins and remaining worker slots (supports --json)
23
- --decision-offload Show offline advisory decision readiness and adoption report
23
+ --decision-offload Show offline advisory decision readiness, adoption and workspace permission report
24
+ --fix With --decision-offload, repair unsafe journal modes and collapsed group masks on non-secret outputs
24
25
  --probe-workers Run bounded worker CLI version probes (default: config-only, no subprocess)
25
26
  --project-local Include project-local artifact diagnostics
26
27
  --json Emit machine-readable output (with --probe-workers: one worker-probe record per CLI; with --deployment: deployment verification; with --decision-offload: offline snapshot; with --resources: host capacity)
@@ -116,7 +116,7 @@ function displayHelp() {
116
116
  ['cost-report --fleet', 'Observe OpenRouter per-bot MTD spend and correlate local activity'],
117
117
  ]);
118
118
  helpGroup('EVIDENCE', [
119
- ['checkpoint create|list|recover', 'Save or inspect a workflow resume position'],
119
+ ['checkpoint create|list|recover', 'Save workflow positions or session handoffs (create --handoff)'],
120
120
  ['evidence export --output <dir>', 'Package portable activity, report, source, eval, and provenance evidence'],
121
121
  ['evidence verify <bundle>', 'Verify every member hash and the bundle checkpoint'],
122
122
  ['effect record|lookup|reconcile', 'Record, look up or reconcile a side effect in the signed effect ledger'],
@@ -12,7 +12,8 @@ export async function refreshDeclaredBundles(ctx, config, frameworks, requested,
12
12
  for (const provider of bundleProviders(config?.installed ?? {}, fw, requested)) {
13
13
  const copyArgs = bundleCopyArgs(config?.installed ?? {}, fw, provider);
14
14
  if (opts.dryRun) {
15
- console.log(` Would re-deploy: ${fw} for ${provider} — aiwg use ${bundleUseName(fw)} --provider ${provider}${copyArgs.length ? ` ${copyArgs.join(' ')}` : ''}`);
15
+ if (!opts.quiet)
16
+ console.log(` Would re-deploy: ${fw} for ${provider} — aiwg use ${bundleUseName(fw)} --provider ${provider}${copyArgs.length ? ` ${copyArgs.join(' ')}` : ''}`);
16
17
  continue;
17
18
  }
18
19
  const result = await withInstalledSelection(ctx.cwd, config?.installed, () => opts.handler.execute({ ...ctx, frameworkRoot: opts.frameworkRoot,