@aiwg/cli 2026.11.1 → 2026.11.2

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 (108) 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/model-capabilities.v1.json +27 -23
  4. package/agentic/code/providers/model-catalog.v1.json +3 -3
  5. package/dist/src/artifacts/cli.js +10 -11
  6. package/dist/src/artifacts/discover-cli-help.js +25 -0
  7. package/dist/src/artifacts/discover-session-facets.js +2 -1
  8. package/dist/src/artifacts/fortemi-core-prebuilt-freshness.js +28 -0
  9. package/dist/src/artifacts/fortemi-core-sync.js +3 -0
  10. package/dist/src/artifacts/framework-capabilities.js +4 -0
  11. package/dist/src/artifacts/framework-source-digest.js +1 -1
  12. package/dist/src/artifacts/index-builder.js +10 -10
  13. package/dist/src/artifacts/index-dependencies.js +72 -0
  14. package/dist/src/artifacts/query-engine-discover-output.js +13 -5
  15. package/dist/src/artifacts/query-engine-discover.js +49 -21
  16. package/dist/src/artifacts/query-engine-entries.js +56 -2
  17. package/dist/src/artifacts/query-engine-options.js +14 -1
  18. package/dist/src/artifacts/query-engine-scoring.js +8 -4
  19. package/dist/src/artifacts/query-engine-show-card.js +2 -0
  20. package/dist/src/artifacts/query-engine-show-load.js +1 -1
  21. package/dist/src/artifacts/query-engine-show.js +3 -1
  22. package/dist/src/artifacts/query-engine-templates.js +33 -0
  23. package/dist/src/artifacts/query-engine-verbose.js +25 -0
  24. package/dist/src/artifacts/relations-builder.js +49 -4
  25. package/dist/src/artifacts/relations.js +9 -0
  26. package/dist/src/artifacts/template-references.js +42 -0
  27. package/dist/src/artifacts/types.js +1 -1
  28. package/dist/src/cli/handlers/bundle-reconciliation.js +7 -3
  29. package/dist/src/cli/handlers/checkpoint-handoff.js +48 -0
  30. package/dist/src/cli/handlers/checkpoint-record.js +20 -0
  31. package/dist/src/cli/handlers/checkpoint.js +50 -17
  32. package/dist/src/cli/handlers/decision.js +1 -1
  33. package/dist/src/cli/handlers/doctor-args.js +3 -1
  34. package/dist/src/cli/handlers/doctor-help.js +2 -1
  35. package/dist/src/cli/handlers/help.js +1 -1
  36. package/dist/src/cli/handlers/refresh-bundles.js +2 -1
  37. package/dist/src/cli/handlers/refresh-managed-deployment.js +196 -0
  38. package/dist/src/cli/handlers/refresh.js +10 -2
  39. package/dist/src/cli/handlers/subcommands-discovery.js +8 -1
  40. package/dist/src/cli/handlers/use.js +10 -3
  41. package/dist/src/cli/services/deployment-verification.js +11 -7
  42. package/dist/src/config/worker-write.js +4 -10
  43. package/dist/src/decision/ledger.js +15 -15
  44. package/dist/src/decision/offload.js +6 -7
  45. package/dist/src/delivery/pr.js +2 -0
  46. package/dist/src/delivery/template-sections.js +56 -0
  47. package/dist/src/extensions/claude-hooks-installer.js +61 -53
  48. package/dist/src/extensions/managed-hook-script-state.js +48 -0
  49. package/dist/src/extensions/muse-managed-hooks.js +49 -0
  50. package/dist/src/issues/cli.js +3 -0
  51. package/dist/src/issues/external-cli.js +4 -1
  52. package/dist/src/issues/live.js +9 -2
  53. package/dist/src/issues/local.js +5 -1
  54. package/dist/src/issues/tracker-policy.js +11 -1
  55. package/dist/src/mcp/json-document.d.mts +2 -0
  56. package/dist/src/models/model-capabilities.v1.json +27 -23
  57. package/dist/src/models/model-catalog.v1.json +3 -3
  58. package/dist/src/models/provider-policy.js +8 -0
  59. package/dist/src/models/worker-health-readiness.js +20 -4
  60. package/dist/src/models/worker-health-snapshot.js +29 -0
  61. package/dist/src/models/worker-installation.d.mts +5 -1
  62. package/dist/src/models/worker-installation.mjs +11 -5
  63. package/dist/src/models/worker-qualification-policy.js +54 -0
  64. package/dist/src/providers/skill-ownership.d.mts +1 -0
  65. package/dist/src/providers/transformation-receipt-integration.js +4 -2
  66. package/dist/src/providers/transformation-receipt.js +4 -2
  67. package/dist/src/serve/worker-invocation.js +4 -2
  68. package/dist/src/smiths/context-pipeline/workspace-audit.js +34 -17
  69. package/dist/src/smiths/context-pipeline/workspace-context-shared.js +12 -6
  70. package/dist/src/smiths/context-pipeline/workspace-doctor.js +44 -4
  71. package/dist/src/smiths/context-pipeline/workspace-document.js +5 -2
  72. package/dist/src/smiths/context-pipeline/workspace-migration.js +2 -1
  73. package/dist/src/smiths/hook-bridge/codex-translator.js +150 -94
  74. package/dist/src/smiths/hook-bridge/codex-trust.js +50 -0
  75. package/dist/src/smiths/hook-bridge/factory-hook-config.js +132 -0
  76. package/dist/src/smiths/hook-bridge/factory-translator.js +88 -33
  77. package/dist/src/smiths/hook-bridge/index.js +3 -3
  78. package/dist/src/smiths/hook-bridge/loader.js +10 -2
  79. package/dist/src/smiths/hook-bridge/prompt-discovery-gaps.js +0 -1
  80. package/dist/src/storage/workspace-permissions-health.js +64 -0
  81. package/dist/src/storage/workspace-permissions.js +51 -0
  82. package/package.json +6 -1
  83. package/tools/agents/providers/base-files.mjs +2 -1
  84. package/tools/agents/providers/base-flat-artifacts.mjs +6 -3
  85. package/tools/agents/providers/base-models-platforms.mjs +3 -3
  86. package/tools/agents/providers/base-skill-copy.mjs +2 -0
  87. package/tools/agents/providers/bound-rules-pointer.mjs +21 -0
  88. package/tools/agents/providers/claude-post-deploy.mjs +9 -5
  89. package/tools/agents/providers/codex-post-deploy.mjs +10 -0
  90. package/tools/agents/providers/factory-hooks.mjs +43 -0
  91. package/tools/agents/providers/factory.mjs +4 -91
  92. package/tools/agents/providers/muse-hooks.mjs +4 -43
  93. package/tools/agents/providers/muse-prompt-discovery.mjs +3 -7
  94. package/tools/agents/providers/packaged-codex-agents.mjs +48 -0
  95. package/tools/agents/providers/rule-delivery-surface.mjs +4 -4
  96. package/tools/agents/providers/rule-presentation.mjs +6 -5
  97. package/tools/agents/providers/rule-projection.mjs +10 -2
  98. package/tools/agents/providers/rule-startup.mjs +8 -1
  99. package/tools/cli/decision-offload-report.mjs +7 -2
  100. package/tools/plugin/issue-template-copies.mjs +24 -0
  101. package/tools/plugin/package-plugins.mjs +11 -3
  102. package/tools/ralph-external/lib/factory-adapter.mjs +7 -8
  103. package/tools/ralph-external/lib/worker-artifacts.mjs +4 -2
  104. package/tools/ralph-external/lib/worker-final.mjs +43 -8
  105. package/tools/ralph-external/lib/worker-launch-cli.mjs +10 -1
  106. package/tools/ralph-external/lib/worker-prompt.mjs +35 -0
  107. package/tools/ralph-external/lib/worker-run-directory-refusal.mjs +8 -0
  108. package/tools/ralph-external/session-launcher.mjs +10 -7
@@ -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) };
@@ -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,
@@ -0,0 +1,196 @@
1
+ // Detect managed hook registration/script drift and outdated rule headers without writes.
2
+ import fs from 'node:fs/promises';
3
+ import path from 'node:path';
4
+ import { isDeepStrictEqual } from 'node:util';
5
+ import { lt, valid } from 'semver';
6
+ import { managedClaudeHooks } from '../../extensions/claude-hooks-installer.js';
7
+ import { AIWG_MANAGED_HOOKS } from '../../extensions/muse-managed-hooks.js';
8
+ import { managedHookScriptState } from '../../extensions/managed-hook-script-state.js';
9
+ import { managedFactoryHooks } from '../../smiths/hook-bridge/factory-translator.js';
10
+ import { readFactoryDocument } from '../../smiths/hook-bridge/factory-hook-config.js';
11
+ import { loadHookSources } from '../../smiths/hook-bridge/loader.js';
12
+ import { parseJson } from '../../mcp/json-document.mjs';
13
+ import { getProviderArtifactPathStrings } from '../../providers/provider-definitions.js';
14
+ import * as ui from '../ui.js';
15
+ import { getFortemiCorePrebuiltStatus } from '../../artifacts/fortemi-core-sync.js';
16
+ import { fortemiCorePrebuiltRepairHint } from '../../artifacts/fortemi-core-prebuilt-freshness.js';
17
+ import { inferInstallationMethod } from '../../installation/manager.mjs';
18
+ export function sourcePrebuiltIndexRepairHint(frameworkRoot) {
19
+ if (inferInstallationMethod(frameworkRoot) !== 'source')
20
+ return null;
21
+ const status = getFortemiCorePrebuiltStatus('framework', frameworkRoot);
22
+ if (status.built && !status.stale)
23
+ return null;
24
+ return `${status.reason ?? 'prebuilt framework index is missing'} — ${fortemiCorePrebuiltRepairHint(frameworkRoot)}`;
25
+ }
26
+ async function readJson(file) {
27
+ try {
28
+ const doc = parseJson(await fs.readFile(file, 'utf8'));
29
+ if (!doc || typeof doc !== 'object' || Array.isArray(doc))
30
+ throw new Error('Expected an object');
31
+ return doc;
32
+ }
33
+ catch (error) {
34
+ if (error.code === 'ENOENT')
35
+ return {};
36
+ throw error;
37
+ }
38
+ }
39
+ function groups(doc, event) {
40
+ const hooks = doc.hooks;
41
+ return Array.isArray(hooks?.[event]) ? hooks[event] : [];
42
+ }
43
+ async function staleHooks(projectRoot, frameworkRoot, provider) {
44
+ if (!['claude', 'muse', 'factory'].includes(provider))
45
+ return [];
46
+ const file = provider === 'claude' ? '.claude/settings.json' : `.${provider}/hooks.json`;
47
+ let doc;
48
+ // Factory hooks.json is a top-level event map (older AIWG wrote it nested); normalize both (#3971).
49
+ try {
50
+ doc = provider === 'factory' ? readFactoryDocument(path.join(projectRoot, file)) : await readJson(path.join(projectRoot, file));
51
+ }
52
+ catch {
53
+ return [{ name: `${provider} managed hooks`, file, reason: 'unreadable' }];
54
+ }
55
+ const stale = [];
56
+ if (provider === 'factory') {
57
+ for (const hook of managedFactoryHooks()) {
58
+ const candidates = groups(doc, hook.event).flatMap(group => Array.isArray(group?.hooks) ? group.hooks : [])
59
+ .filter(entry => entry && (entry._aiwg_id === hook.id || entry.command === hook.command));
60
+ if (!candidates.some(entry => entry.type === 'command' && entry.command === hook.command
61
+ && entry._aiwg_managed === true && entry._aiwg_id === hook.id)) {
62
+ stale.push({ name: `${hook.event} → ${hook.id}`, file, reason: candidates.length ? 'outdated' : 'missing' });
63
+ }
64
+ }
65
+ }
66
+ else if (provider === 'claude') {
67
+ const source = path.join(frameworkRoot, 'agentic/code/addons/aiwg-hooks/hooks');
68
+ let sourceFiles;
69
+ try {
70
+ sourceFiles = await fs.readdir(source);
71
+ }
72
+ catch (error) {
73
+ if (error.code === 'ENOENT')
74
+ return [];
75
+ throw error;
76
+ }
77
+ for (const hook of managedClaudeHooks(sourceFiles)) {
78
+ const candidates = groups(doc, hook.event).flatMap(group => Array.isArray(group?.hooks) ? group.hooks : [])
79
+ .filter(entry => entry && (entry._aiwg_id === hook.hookId ||
80
+ (typeof entry.command === 'string' && entry.command.includes(hook.script))));
81
+ const current = candidates.some(entry => entry.type === 'command' && entry.command === hook.command &&
82
+ entry._aiwg_managed === true && entry._aiwg_id === hook.hookId);
83
+ if (!current)
84
+ stale.push({ name: `${hook.event} → ${hook.hookId}`, file, reason: candidates.length ? 'outdated' : 'missing' });
85
+ }
86
+ }
87
+ else {
88
+ // Muse cannot carry in-band ids. Its sidecar supplies identity for older commands.
89
+ let recorded = [];
90
+ try {
91
+ const sidecar = await readJson(path.join(projectRoot, '.muse/.aiwg-hooks.json'));
92
+ if (Array.isArray(sidecar.hooks))
93
+ recorded = sidecar.hooks;
94
+ }
95
+ catch { /* The live document still proves canonical registrations without a sidecar. */ }
96
+ for (const hook of AIWG_MANAGED_HOOKS) {
97
+ const deployed = groups(doc, hook.event);
98
+ if (deployed.some(group => isDeepStrictEqual(group, hook.group)))
99
+ continue;
100
+ const previous = recorded.find(entry => entry?.id === hook.id);
101
+ const exists = deployed.some(group => isDeepStrictEqual(group, previous?.group) ||
102
+ group?.hooks?.some(entry => entry?.command === hook.group.hooks[0].command));
103
+ stale.push({ name: `${hook.event} → ${hook.id}`, file, reason: exists ? 'outdated' : 'missing' });
104
+ }
105
+ }
106
+ return stale;
107
+ }
108
+ async function staleRules(projectRoot, provider, version) {
109
+ const directory = getProviderArtifactPathStrings(provider)?.rules;
110
+ if (!directory || path.isAbsolute(directory) || directory.startsWith('~'))
111
+ return [];
112
+ const stale = [];
113
+ async function visit(relative) {
114
+ let entries;
115
+ try {
116
+ entries = await fs.readdir(path.join(projectRoot, relative), { withFileTypes: true });
117
+ }
118
+ catch (error) {
119
+ if (error.code !== 'ENOENT')
120
+ throw error;
121
+ return;
122
+ }
123
+ await Promise.all(entries.map(async (entry) => {
124
+ const file = path.join(relative, entry.name);
125
+ if (entry.isDirectory())
126
+ return visit(file);
127
+ if (!entry.isFile() || !/\.(md|mdc)$/.test(entry.name))
128
+ return;
129
+ const content = await fs.readFile(path.join(projectRoot, file), 'utf8');
130
+ const marker = /^(?:#|<!--)\s*aiwg:managed\s+v([^\s>]+)([^\r\n]*)/m.exec(content);
131
+ if (!marker || /\bproject-local\b/.test(marker[2]))
132
+ return;
133
+ const older = valid(marker[1]) && valid(version) ? lt(marker[1], version) : marker[1] !== version;
134
+ if (older)
135
+ stale.push({ name: `${file} (v${marker[1]} → v${version})`, file, reason: 'outdated' });
136
+ }));
137
+ }
138
+ await visit(directory);
139
+ return stale;
140
+ }
141
+ async function staleHookScripts(projectRoot, frameworkRoot, provider) {
142
+ const source = path.join(frameworkRoot, 'agentic/code/addons/aiwg-hooks/hooks');
143
+ const scripts = new Map();
144
+ if (provider === 'claude') {
145
+ let files;
146
+ try {
147
+ files = await fs.readdir(source);
148
+ }
149
+ catch (error) {
150
+ if (error.code === 'ENOENT')
151
+ return [];
152
+ throw error;
153
+ }
154
+ for (const hook of managedClaudeHooks(files))
155
+ scripts.set(hook.script, path.join(source, path.basename(hook.script)));
156
+ }
157
+ else if (provider === 'muse') {
158
+ scripts.set('.muse/hooks/aiwg-prompt-discovery.cjs', path.join(source, 'aiwg-prompt-discovery.cjs'));
159
+ }
160
+ else if (provider === 'codex' || provider === 'factory') {
161
+ // Match installCodexPromptDiscovery: resolve packaged canonical arguments,
162
+ // not the portable launcher command emitted into hooks.json.
163
+ const { sources, errors } = await loadHookSources(frameworkRoot);
164
+ if (errors.length)
165
+ throw new Error(errors.join('\n'));
166
+ const hook = sources.find(entry => entry.id === 'aiwg-prompt-discovery');
167
+ if (hook?.args?.[0])
168
+ scripts.set(`.${provider}/hooks/aiwg-prompt-discovery.cjs`, hook.args[0]);
169
+ }
170
+ const stale = [];
171
+ for (const [file, sourceFile] of scripts) {
172
+ // Each provider currently copies these bytes verbatim; registrations may
173
+ // transform commands independently (notably Codex's portable launcher).
174
+ const reason = await managedHookScriptState(projectRoot, file, await fs.readFile(sourceFile));
175
+ if (reason)
176
+ stale.push({ name: file, file, reason });
177
+ }
178
+ return stale;
179
+ }
180
+ export async function checkManagedDeployment(options) {
181
+ const { projectRoot, frameworkRoot, provider, quiet } = options;
182
+ const pkg = await readJson(path.join(frameworkRoot, 'package.json'));
183
+ const [hooks, scripts, rules] = await Promise.all([
184
+ staleHooks(projectRoot, frameworkRoot, provider),
185
+ staleHookScripts(projectRoot, frameworkRoot, provider),
186
+ typeof pkg.version === 'string' ? staleRules(projectRoot, provider, pkg.version) : [],
187
+ ]);
188
+ const stale = [...hooks, ...scripts, ...rules].sort((a, b) => a.name.localeCompare(b.name));
189
+ if (stale.length && !quiet) {
190
+ for (const item of stale)
191
+ ui.warn(`Stale deployment: ${item.reason} ${item.name} — ${item.file}${item.reason === 'operator-edited' ? ' (kept; review operator edits before redeploying)' : ''}`);
192
+ ui.warn(`Fix this deployment: aiwg use all --provider ${provider}`);
193
+ }
194
+ return stale;
195
+ }
196
+ //# sourceMappingURL=refresh-managed-deployment.js.map
@@ -22,6 +22,7 @@ import { createUseHandler } from './use.js';
22
22
  import { automaticRemovalAllowed } from '../../providers/deployment-preservation.mjs';
23
23
  import { refreshDeclaredBundles } from './refresh-bundles.js';
24
24
  import { bundledRuleOutputNames } from './refresh-rule-inventory.js';
25
+ import { checkManagedDeployment, sourcePrebuiltIndexRepairHint } from './refresh-managed-deployment.js';
25
26
  import { getFrameworkRoot } from '../../channel/manager.mjs';
26
27
  import { refreshAllPackages } from '../../packages/registry.js';
27
28
  import { resolveActiveProvider } from '../provider-resolution.js';
@@ -606,6 +607,7 @@ export const refreshHandler = {
606
607
  ui.warn('--prune-tracked has no effect without --prune-other-providers; nothing was removed.');
607
608
  }
608
609
  let staleAgentRemovals = [];
610
+ let staleManagedDeployments = [];
609
611
  let trackedSkipped = [];
610
612
  // A dry run still reports what a real run would remove. Skipping the pass
611
613
  // entirely meant `refresh --dry-run` printed "Checking for stale deployments..."
@@ -688,7 +690,7 @@ export const refreshHandler = {
688
690
  try {
689
691
  const { getFrameworkRoot } = await import('../../channel/manager.mjs');
690
692
  const { join } = await import('path');
691
- const config = await readAiwgConfig(process.cwd());
693
+ const config = await readAiwgConfig(ctx.cwd);
692
694
  if (config) {
693
695
  const MANIFEST_PATHS = {
694
696
  sdlc: 'agentic/code/frameworks/sdlc-complete/manifest.json',
@@ -697,6 +699,7 @@ export const refreshHandler = {
697
699
  research: 'agentic/code/frameworks/research-complete/manifest.json',
698
700
  };
699
701
  const frameworkRoot = await getFrameworkRoot();
702
+ staleManagedDeployments = await checkManagedDeployment({ projectRoot: ctx.cwd, frameworkRoot, provider: detectedProvider, quiet });
700
703
  // Batch-hash manifests in parallel instead of serially awaiting each
701
704
  // one. For ~10 frameworks this cuts refresh latency from ~N*I/O to
702
705
  // max-single-I/O on a warm filesystem (#919 cleanup).
@@ -724,7 +727,7 @@ export const refreshHandler = {
724
727
  : `Deployments current, but ${removed} stale artifact(s) were removed this run — review the list above`);
725
728
  }
726
729
  }
727
- else {
730
+ else if (staleManagedDeployments.length === 0) {
728
731
  if (!quiet)
729
732
  ui.success('All deployments up to date');
730
733
  }
@@ -778,6 +781,9 @@ export const refreshHandler = {
778
781
  }
779
782
  }
780
783
  // Step 5: Health check
784
+ const prebuiltIndexRepair = dryRun ? null : sourcePrebuiltIndexRepairHint(frameworkRoot);
785
+ if (prebuiltIndexRepair && !quiet)
786
+ ui.warn(prebuiltIndexRepair);
781
787
  if (!quiet)
782
788
  ui.info(dryRun ? 'Would run health check...' : 'Running health check...');
783
789
  if (!dryRun) {
@@ -819,8 +825,10 @@ export const refreshHandler = {
819
825
  skipUpdate,
820
826
  channel: channel || undefined,
821
827
  staleAgentRemovals,
828
+ staleManagedDeployments,
822
829
  deploymentFailures,
823
830
  updateFailure,
831
+ prebuiltIndexRepair,
824
832
  });
825
833
  console.log(output);
826
834
  }