agentic-workflow-manager 8.2.0 → 8.3.0

package/dist/src/commands/hooks/claude.js

@@ -19,6 +19,43 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const providers_1 = require("../../providers");
 const shared_1 = require("./shared");
+const provider_1 = require("../../core/context/provider");
+const orchestrators_1 = require("../../core/orchestrators");
+/**
+ * Materializa el payload compuesto (using-awm + orquestadores declarados) en `skillDest`.
+ *
+ * Antes `using-awm.md` era un symlink al SKILL.md crudo del registry: todo lo que
+ * `buildContext` compone (declared orchestrators — Tasks 1-4) nunca llegaba a Claude
+ * Code, el proveedor PRINCIPAL que este framework existe para servir. Se escribe el
+ * archivo en vez de enlazarlo porque el contenido ya no es un archivo del registry sino
+ * un derivado suyo — igual que `materialize()` hace para los demas proveedores
+ * (core/context/materializer.ts), solo que aca el destino es el propio scriptsDir del
+ * hook en vez del awm-context.md generico.
+ *
+ * Usada por `installClaudeHook` Y por `resyncClaudeHookFiles` — con proposito: si solo
+ * una de las dos escribiera el payload materializado, la otra seguiria symlinkeando al
+ * SKILL.md crudo y el siguiente `awm update` reabriria el mismo bypass que esto cierra.
+ *
+ * Escritura atomica via write-then-rename (post-implementation-qa Finding 1, TOCTOU):
+ * el patron previo (`unlinkSync` seguido de `writeFileSync`) dejaba una ventana entre
+ * ambas llamadas donde un symlink recreado en `skillDest` seria seguido por
+ * `writeFileSync` (que no usa `O_EXCL`), escribiendo a traves de el sobre lo que sea
+ * que apunte. Escribir a un temporal unico en el MISMO directorio (para que el rename
+ * quede en el mismo filesystem y sea atomico) y luego `renameSync` al destino evita eso
+ * por completo: el rename reemplaza la entrada de directorio de forma atomica sin
+ * dereferenciar un symlink preexistente en el destino, y sin ventana entre borrar y
+ * escribir — no hace falta unlink previo, el rename ya sobrescribe en un solo paso.
+ */
+function writeMaterializedSkill(skillDest, registryRoot) {
+    const ctx = (0, provider_1.buildContext)({
+        registryRoot,
+        profileExtensions: [],
+        declaredOrchestrators: (0, orchestrators_1.collectAndWarn)(),
+    });
+    const tmpPath = path_1.default.join(path_1.default.dirname(skillDest), `.using-awm.md.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    fs_1.default.writeFileSync(tmpPath, ctx.markdown, 'utf-8');
+    fs_1.default.renameSync(tmpPath, skillDest);
+}
 function isAwmEntry(entry, scriptsDir, matcher) {
     return (entry?.matcher === matcher &&
         Array.isArray(entry?.hooks) &&
@@ -39,19 +76,10 @@ function installClaudeHook(options) {
     fs_1.default.mkdirSync(config.scriptsDir, { recursive: true });
     (0, shared_1.syncExecutable)(path_1.default.join(sourceHooks, 'session-start'), path_1.default.join(config.scriptsDir, 'session-start'), options.installMethod);
     (0, shared_1.syncExecutable)(path_1.default.join(sourceHooks, 'run-hook.cmd'), path_1.default.join(config.scriptsDir, 'run-hook.cmd'), options.installMethod);
-    // 3. Link the skill (default: symlink so 'awm update' propagates; fall back to copy if symlink is unavailable, e.g. Windows without Developer Mode)
+    // 3. Materializar el payload compuesto (using-awm + orquestadores declarados) — ver
+    //    writeMaterializedSkill arriba para por que esto ya no es un symlink al SKILL.md crudo.
     const skillDest = path_1.default.join(config.scriptsDir, 'using-awm.md');
-    try {
-        fs_1.default.unlinkSync(skillDest);
-    }
-    catch { /* not exists */ }
-    try {
-        fs_1.default.symlinkSync(sourceSkill, skillDest, 'file'); // ver shared.ts: el tipo no se infiere
-    }
-    catch {
-        // best-effort: copy the single skill file; 'awm update' will not auto-propagate
-        fs_1.default.copyFileSync(sourceSkill, skillDest);
-    }
+    writeMaterializedSkill(skillDest, options.registryRoot);
     // 4. Backup settings if it exists
     const backupPath = (0, shared_1.backupManagedFile)(config.settingsPath);
     // 5. Read or initialize settings
@@ -178,29 +206,17 @@ function uninstallClaudeHook(agent) {
 /** Refresh the Claude hook's script/skill files in place (used by resync). Assumes the caller has verified the settings entry is already present. */
 function resyncClaudeHookFiles(config, registryRoot, method) {
     const sourceHooks = path_1.default.join(registryRoot, 'hooks');
-    const sourceSkill = path_1.default.join(registryRoot, 'skills/using-awm/SKILL.md');
     fs_1.default.mkdirSync(config.scriptsDir, { recursive: true });
     (0, shared_1.syncExecutable)(path_1.default.join(sourceHooks, 'session-start'), path_1.default.join(config.scriptsDir, 'session-start'), method);
     (0, shared_1.syncExecutable)(path_1.default.join(sourceHooks, 'run-hook.cmd'), path_1.default.join(config.scriptsDir, 'run-hook.cmd'), method);
+    // Re-materializar el payload compuesto igual que `installClaudeHook` (arriba) — NO
+    // volver a symlinkear al SKILL.md crudo. Antes este era el segundo escritor del mismo
+    // archivo con el symlink-con-fallback-a-copia; si solo `installClaudeHook` se hubiera
+    // arreglado y este no, el primer `awm update` posterior a un install correcto habria
+    // sobreescrito el payload materializado con un symlink crudo de nuevo — reabriendo el
+    // bypass que esto existe para cerrar.
     const skillDest = path_1.default.join(config.scriptsDir, 'using-awm.md');
-    try {
-        fs_1.default.unlinkSync(skillDest);
-    }
-    catch { /* not exists */ }
-    // Mismo fallback a copia que `installClaudeHook` (arriba). Sin el, en
-    // Windows sin Developer Mode este symlink tira EPERM, `resyncInstalledHooks`
-    // propaga el throw y `awm update` devuelve 1 — PARA SIEMPRE: el install
-    // funcionaba (tenia el fallback) y el update no, en una plataforma que la
-    // matriz de soporte declara verificada en CI. Dos escritores del mismo
-    // archivo, solo uno endurecido.
-    try {
-        fs_1.default.symlinkSync(sourceSkill, skillDest, 'file'); // ver shared.ts: el tipo no se infiere
-    }
-    catch {
-        // best-effort: `awm update` no auto-propagara cambios de esta skill,
-        // pero el hook queda funcional en vez de dejar el comando inservible.
-        fs_1.default.copyFileSync(sourceSkill, skillDest);
-    }
+    writeMaterializedSkill(skillDest, registryRoot);
 }
 /** True when the registry has everything needed to resync the Claude hook files. */
 function claudeResyncSourcesExist(registryRoot) {

package/dist/src/commands/hooks/index.js

@@ -58,7 +58,7 @@ function registerHooksCommand(program) {
             console.log(`  Scripts:        ${result.scriptsDir}/session-start`);
             if (agent === 'claude-code') {
                 console.log(`                  ${result.scriptsDir}/run-hook.cmd`);
-                console.log(`                  ${result.scriptsDir}/using-awm.md → ~/.awm/registries/baseline/skills/using-awm/SKILL.md`);
+                console.log(`                  ${result.scriptsDir}/using-awm.md (composed context, written)`);
             }
             console.log('');
             console.log(`  Settings file:  ${result.settingsPath}`);

package/dist/src/commands/hooks/shared.js

@@ -108,7 +108,7 @@ function checkFile(file) {
         return { ok: true, detail: file };
     }
     catch {
-        return { ok: false, detail: `broken link: ${file}` };
+        return { ok: false, detail: `cannot read file: ${file}` };
     }
 }
 /**

package/dist/src/commands/registry/add.js

@@ -12,6 +12,7 @@ const simple_git_1 = __importDefault(require("simple-git"));
 const registries_1 = require("../../core/registries");
 const discovery_1 = require("../../core/discovery");
 const bundles_1 = require("../../core/bundles");
+const orchestrators_1 = require("../../core/orchestrators");
 function deriveRegistryName(remote) {
     // Split on '/', '\' and ':' — not just '/' and ':'. A git remote URL
     // (https://…/repo.git, git@host:org/repo.git) only ever uses the first
@@ -66,6 +67,10 @@ async function addRegistry(remote, nameOverride) {
         fs_1.default.rmSync(dest, { recursive: true, force: true });
         return { ok: false, name, error: e instanceof Error ? e.message : String(e) };
     }
+    // Una declaracion de orquestador malformada se REPORTA, no aborta: el
+    // registry puede aportar skills utiles aunque su declaracion este rota,
+    // y abortar por eso invalidaria contenido sano (R1.2).
+    const { diagnostics: orchestratorDiagnostics } = (0, orchestrators_1.readDeclaredOrchestrators)(dest);
     (0, registries_1.writeRegistriesConfig)([...existing, { name, remote }]);
-    return { ok: true, name, contentRoot: dest };
+    return { ok: true, name, contentRoot: dest, orchestratorDiagnostics };
 }

package/dist/src/commands/registry/index.js

@@ -38,6 +38,9 @@ function registerRegistryCommand(program) {
             process.exit(1);
         }
         s.stop(`Registry ${picocolors_1.default.cyan(result.name)} added at ${result.contentRoot}`);
+        for (const d of result.orchestratorDiagnostics) {
+            console.warn(picocolors_1.default.yellow(`  ⚠  ${d}`));
+        }
         try {
             (0, regenerate_1.regenerateGlobalContext)();
         }

package/dist/src/commands/sensors/compatibility/live.js

@@ -85,6 +85,7 @@ async function resolveParsedPackCompatibility(cwd, pack, options = {}) {
                 environment: variant.command.environment,
                 configFiles: evidence.configFiles,
                 scripts: evidence.scripts,
+                variantArgs: variant.command.args,
             })
             : null;
         sensors[name] = (0, resolve_1.resolveProjectCompatibility)({ ...executionPack, sensors: { [name]: sensor } }, { ...resolutionEvidence, probe: probe ?? undefined }).sensors[name];

package/dist/src/commands/sensors/compatibility/probe.js

@@ -24,11 +24,23 @@ function commandFor(kind, evidence) {
     };
     if (kind === 'version')
         return { ...command, args: ['--version'] };
+    // A pack asset is never named the tool's default config filename (e.g.
+    // `eslint.config.awm.mjs`, not `eslint.config.js`), so the real command always
+    // pins it via an explicit `--config <file>`. Mirroring that same pair here — rather
+    // than probing with a bare invocation — is what lets the probe find the config the
+    // real run will actually use, for whatever name or tool version is in play.
     if (kind === 'eslint-print-config')
-        return { ...command, args: ['--print-config', evidence.configFiles?.[0] ?? 'package.json'] };
+        return { ...command, args: [...configFlag(evidence.variantArgs), '--print-config', evidence.configFiles?.[0] ?? 'package.json'] };
     if (kind === 'typescript-show-config')
-        return { ...command, args: ['--showConfig'] };
-    return { ...command, args: ['--validate'] };
+        return { ...command, args: [...configFlag(evidence.variantArgs), '--showConfig'] };
+    return { ...command, args: [...configFlag(evidence.variantArgs), '--validate'] };
+}
+/** The `--config <file>` pair from a variant's real command args, if it declares one. */
+function configFlag(variantArgs) {
+    if (!variantArgs)
+        return [];
+    const i = variantArgs.indexOf('--config');
+    return i !== -1 && variantArgs[i + 1] !== undefined ? ['--config', variantArgs[i + 1]] : [];
 }
 /** Executes only the closed probe enum. Raw output is intentionally discarded. */
 async function runCompatibilityProbe(probe, evidence, executor = exec_1.runStructuredCommand) {

package/dist/src/commands/sensors/status.js

@@ -145,10 +145,14 @@ async function computeSensorStatus(cwd = process.cwd()) {
         const raw = JSON.parse(fs_1.default.readFileSync(manifestPath, 'utf-8'));
         const parsed = (0, manifest_1.parseSensorManifest)(raw, manifestPath);
         if (parsed.kind === 'v2') {
+            // Monorepo support (mirrors run.ts/init.ts): detection and structured-command
+            // asset resolution both need to see the real package, not the (possibly
+            // unrelated) directory the manifest lives in.
+            const projectCwd = parsed.pack.packageRoot ? path_1.default.resolve(cwd, parsed.pack.packageRoot) : cwd;
             const checks = {};
             let compatibility;
             try {
-                compatibility = resolveStaticV2Compatibility(cwd, parsed.pack);
+                compatibility = resolveStaticV2Compatibility(projectCwd, parsed.pack);
             }
             catch (error) {
                 const detail = error instanceof Error ? error.message : 'live compatibility unavailable';
@@ -163,7 +167,7 @@ async function computeSensorStatus(cwd = process.cwd()) {
                     continue;
                 }
                 checks[name] = staticCompatibilityCheck(sensor, compatibility[name])
-                    ?? checkStructuredCommand(sensor.command, cwd, sensor.assets);
+                    ?? checkStructuredCommand(sensor.command, projectCwd, sensor.assets);
             }
             return { overall: Object.keys(checks).length > 0 && Object.values(checks).every(check => check.ok) ? 'READY' : 'DEGRADED', pack: parsed.pack.pack, checks };
         }

package/dist/src/core/context/orchestrator.js

@@ -8,6 +8,7 @@ const config_instructions_1 = require("./strategies/config-instructions");
 const codex_agents_1 = require("./strategies/codex-agents");
 const provider_1 = require("./provider");
 const materializer_1 = require("./materializer");
+const orchestrators_1 = require("../orchestrators");
 class InjectionOrchestrator {
     overrides;
     constructor(overrides = {}) {
@@ -41,7 +42,11 @@ class InjectionOrchestrator {
     }
     /** Full input: builds context from registry and materializes to disk. Used by installContext only. */
     inputFor(op) {
-        const ctx = (0, provider_1.buildContext)({ registryRoot: op.registryRoot, profileExtensions: op.profileExtensions });
+        const ctx = (0, provider_1.buildContext)({
+            registryRoot: op.registryRoot,
+            profileExtensions: op.profileExtensions,
+            declaredOrchestrators: (0, orchestrators_1.collectAndWarn)(),
+        });
         const absPath = this.contextPathFor(op);
         const ref = (0, materializer_1.materialize)(ctx, absPath, op.scope);
         return {
@@ -66,7 +71,15 @@ class InjectionOrchestrator {
         const absPath = this.contextPathFor(op);
         let contentHash = '';
         try {
-            const ctx = (0, provider_1.buildContext)({ registryRoot: op.registryRoot, profileExtensions: op.profileExtensions });
+            // Debe recolectar declarados igual que inputFor: si no, el hash "esperado" aqui
+            // diverge del hash realmente materializado por installContext en cuanto algun
+            // registry instalado declare un orquestador, y contextStatus reportaria 'stale'
+            // de forma permanente incluso justo despues de un install correcto.
+            const ctx = (0, provider_1.buildContext)({
+                registryRoot: op.registryRoot,
+                profileExtensions: op.profileExtensions,
+                declaredOrchestrators: (0, orchestrators_1.collectAndWarn)(),
+            });
             contentHash = ctx.contentHash;
         }
         catch (err) {

package/dist/src/core/context/provider.js

@@ -16,6 +16,33 @@ function parseVersion(skill) {
     const m = skill.match(/^version:\s*["']?([^"'\n]+)["']?\s*$/m);
     return m ? m[1].trim() : '0.0.0';
 }
+/**
+ * Neutraliza contenido no confiable proveniente de registries declarados
+ * (name/appliesWhen/terminatesTo) antes de interpolarlo en markdown.
+ * Sin esto, un registry malicioso/comprometido podria inyectar saltos de
+ * linea, marcadores markdown (##, `, *, _) o pseudo-tags XML/HTML (<, >)
+ * para forjar una seccion nueva o un bloque instruccional dentro del
+ * payload de contexto que consume el proveedor de IA — un vector de
+ * prompt-injection. `readDeclaredOrchestrators` solo valida que los
+ * campos sean strings no vacios; el saneo pertenece a esta frontera de
+ * render, no a la validacion de lectura.
+ */
+function sanitizeForMarkdown(s) {
+    return s.replace(/\r?\n/g, ' ').replace(/[`*_#<>]/g, '');
+}
+function renderDeclared(list) {
+    if (list.length === 0)
+        return '';
+    const rows = list
+        .map(o => {
+        const name = sanitizeForMarkdown(o.name);
+        const appliesWhen = sanitizeForMarkdown(o.appliesWhen);
+        const terminatesTo = sanitizeForMarkdown(o.terminatesTo);
+        return `- **${name}** — applies when: ${appliesWhen}. Terminates to: \`${terminatesTo}\`.`;
+    })
+        .join('\n');
+    return `## Declared orchestrators\n\nConsider these before the built-in pair:\n\n${rows}\n\n`;
+}
 function buildContext(input) {
     const skillPath = path_1.default.join(input.registryRoot, 'skills/using-awm/SKILL.md');
     if (!fs_1.default.existsSync(skillPath)) {
@@ -24,6 +51,7 @@ function buildContext(input) {
     const skill = fs_1.default.readFileSync(skillPath, 'utf-8');
     const exts = input.profileExtensions.length ? input.profileExtensions.join(', ') : 'none';
     const header = `<!-- AWM context (generated) -->\n# AWM\n\nActive extensions: ${exts}\n\n`;
-    const markdown = header + skill;
+    const declared = renderDeclared(input.declaredOrchestrators ?? []);
+    const markdown = header + declared + skill;
     return { markdown, sourceVersion: parseVersion(skill), contentHash: sha256(markdown) };
 }

package/dist/src/core/context/regenerate.js

@@ -13,11 +13,28 @@ exports.regenerateGlobalContext = regenerateGlobalContext;
 const fs_1 = __importDefault(require("fs"));
 const providers_1 = require("../../providers");
 const registries_1 = require("../registries");
+const orchestrators_1 = require("../orchestrators");
 const orchestrator_1 = require("./orchestrator");
 function regenerateGlobalContext(targets = [...providers_1.AGENT_TARGETS], orch = new orchestrator_1.InjectionOrchestrator()) {
     const skillsRoot = (0, registries_1.capabilityRoot)('skills');
     if (!skillsRoot)
         return [];
+    // Print each declared-orchestrator diagnostic ONCE up front, rather than letting
+    // every agent's contextStatus/installContext call independently re-collect and
+    // re-warn via InjectionOrchestrator.inputFor/statusInputFor (both call
+    // orchestrators.ts's collectAndWarn() internally, unaware of this outer loop). A
+    // single `awm update` touching N agents (e.g. opencode + codex) would otherwise
+    // print the same diagnostic up to 2x per agent (once from statusInputFor, once
+    // from inputFor when stale) — noisy but not incorrect, since no data is lost or
+    // wrong. This only reduces the printing done BY THIS FUNCTION to one line per
+    // diagnostic; inputFor/statusInputFor still call collectAndWarn() internally per
+    // op (they need the declared list to build/hash context), so a per-agent
+    // duplicate can still print alongside this upfront one. Deeper dedup would mean
+    // threading a pre-collected list through ContextOp/InjectionOrchestrator, which
+    // touches shared collection-scope logic other callers (hooks/claude.ts) rely on —
+    // out of proportion for this minor finding.
+    for (const d of (0, orchestrators_1.collectDeclaredOrchestrators)().diagnostics)
+        console.warn(`warning: ${d}`);
     const out = [];
     for (const agent of targets) {
         const inj = (0, providers_1.providerFor)(agent).injection;
@@ -42,6 +59,18 @@ function regenerateGlobalContext(targets = [...providers_1.AGENT_TARGETS], orch
             if (inj.globalPath === null)
                 continue;
         }
+        else if (inj.type === 'cc-settings-merge') {
+            // Claude Code no pasa por este dispatcher generico: su contexto se
+            // materializa via el hook dedicado (hooks/claude.ts's installClaudeHook/
+            // resyncClaudeHookFiles), invocado por `awm update` a traves de un path
+            // separado (hooks/resync.ts's resyncInstalledHooks). Mismo salteo que
+            // stepContextInjection (init/steps.ts) y contextGlobalCheck
+            // (diagnostics/provider-checks.ts) — "covered by hook". Sin este
+            // continue, orch.contextStatus/installContext corrian igual para
+            // claude-code y escribian un ~/.awm/context/awm-context.md huerfano que
+            // nadie lee (el archivo real vive en el scriptsDir del hook).
+            continue;
+        }
         const op = {
             agent,
             scope: 'global',

package/dist/src/core/orchestrators.js

@@ -0,0 +1,142 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readDeclaredOrchestrators = readDeclaredOrchestrators;
+exports.collectDeclaredOrchestrators = collectDeclaredOrchestrators;
+exports.collectAndWarn = collectAndWarn;
+// cli/src/core/orchestrators.ts
+// Lector de declaraciones de orquestador. A diferencia de readRegistryManifest
+// (registries.ts), este parser NUNCA lanza: una declaracion malformada se
+// rechaza y se reporta, sin invalidar el registry que la contiene ni a los
+// demas (R1.2). El contrato admite exactamente cuatro campos — identidad,
+// cuando aplica, y a quien cede el control — y rechaza cualquier otro, que
+// es como se impide que vocabulario de un proceso concreto (o un secreto)
+// entre al framework (R1.3, R5.3).
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const registries_1 = require("./registries");
+const ALLOWED_FIELDS = ['name', 'appliesWhen', 'terminatesTo'];
+// These fields are semantically short (a short identity, a short trigger condition, a
+// short target name) — no legitimate declaration needs more than this. A registry is
+// untrusted input whose fields flow straight into the AI-provider context payload, so an
+// unbounded string here would let a crafted registry bloat/DoS that context.
+const MAX_FIELD_LENGTH = 500;
+function readDeclaredOrchestrators(root) {
+    const file = path_1.default.join(root, registries_1.REGISTRY_MANIFEST_NAME);
+    // Shares the same trust boundary as readRegistryManifest (registries.ts): a manifest
+    // that is a symlink (or otherwise not a regular file) is rejected rather than followed.
+    // assertRegularRegistryFile throws on that case, so it's wrapped locally — this reader
+    // must never throw, only report (R1.2).
+    let exists;
+    try {
+        exists = (0, registries_1.assertRegularRegistryFile)(file);
+    }
+    catch (e) {
+        return { orchestrators: [], diagnostics: [`${file}: ${e instanceof Error ? e.message : String(e)}`] };
+    }
+    if (!exists)
+        return { orchestrators: [], diagnostics: [] };
+    let contents;
+    try {
+        contents = fs_1.default.readFileSync(file, 'utf-8');
+    }
+    catch (e) {
+        return { orchestrators: [], diagnostics: [`${file}: cannot read manifest (${e instanceof Error ? e.message : String(e)})`] };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(contents);
+    }
+    catch (e) {
+        return { orchestrators: [], diagnostics: [`${file}: manifest is not valid JSON (${e instanceof Error ? e.message : String(e)})`] };
+    }
+    const decl = raw?.orchestrator;
+    if (decl === undefined)
+        return { orchestrators: [], diagnostics: [] };
+    if (typeof decl !== 'object' || decl === null || Array.isArray(decl)) {
+        return { orchestrators: [], diagnostics: [`${file}: "orchestrator" must be an object`] };
+    }
+    const problems = [];
+    const entries = decl;
+    for (const key of Object.keys(entries)) {
+        if (!ALLOWED_FIELDS.includes(key)) {
+            // key comes straight from an untrusted registry's JSON — JSON.stringify keeps the
+            // diagnostic single-line and unambiguous even if the key contains newlines or other
+            // control characters, which would otherwise let a crafted key forge extra log lines.
+            problems.push(`unknown field ${JSON.stringify(key)} — the contract admits only ${ALLOWED_FIELDS.join(', ')}`);
+        }
+    }
+    for (const field of ALLOWED_FIELDS) {
+        const value = entries[field];
+        if (typeof value !== 'string' || value.trim() === '') {
+            problems.push(`"${field}" must be a non-empty string`);
+        }
+        else if (value.length > MAX_FIELD_LENGTH) {
+            problems.push(`"${field}" must be at most ${MAX_FIELD_LENGTH} characters`);
+        }
+    }
+    if (problems.length > 0) {
+        return { orchestrators: [], diagnostics: [`${file}: invalid "orchestrator" declaration — ${problems.join('; ')}`] };
+    }
+    return {
+        orchestrators: [{
+                name: entries.name,
+                appliesWhen: entries.appliesWhen,
+                terminatesTo: entries.terminatesTo,
+            }],
+        diagnostics: [],
+    };
+}
+/**
+ * Recolecta declaraciones de orquestador de TODOS los registries instalados (no solo
+ * el que se esta operando) y diagnosticos de las que estan rotas. Nunca lanza:
+ * `readDeclaredOrchestrators` ya garantiza eso por-registry (R1.2), asi que un registry
+ * con declaracion rota se omite del resultado sin impedir construir el contexto (R5.1).
+ *
+ * Vive aca (no en core/context/orchestrator.ts, que la definia originalmente) porque
+ * este modulo es una hoja: solo depende de `./registries`, que a su vez no depende de
+ * nada bajo commands/*. core/context/orchestrator.ts en cambio arrastra
+ * strategies/hook-merge.ts, que importa commands/hooks/install.ts — y claude.ts
+ * necesita esta funcion para cerrar el bypass del SKILL.md crudo (Task 6). Si
+ * `collectAndWarn` siguiera viviendo en orchestrator.ts, que commands/hooks/claude.ts
+ * la importara cerraria un ciclo real: claude.ts -> orchestrator.ts ->
+ * strategies/hook-merge.ts -> commands/hooks/install.ts -> claude.ts.
+ *
+ * Dedupe por "name" entre registries: dos registries instalados pueden declarar el mismo
+ * nombre (posiblemente con appliesWhen/terminatesTo distintos y contradictorios). En vez
+ * de emitir ambas filas al markdown compuesto, gana la primera en el orden de
+ * listRegistries() (= orden de registries.json, ver registries.ts) y la duplicada se
+ * descarta con un diagnostico — misma degradacion tolerante (reportar, no lanzar) que el
+ * resto de este modulo (R1.2, R5.1).
+ */
+function collectDeclaredOrchestrators() {
+    const declared = [];
+    const diagnostics = [];
+    const seenNames = new Set();
+    for (const reg of (0, registries_1.listRegistries)()) {
+        const r = readDeclaredOrchestrators(reg.contentRoot);
+        for (const orch of r.orchestrators) {
+            if (seenNames.has(orch.name)) {
+                const file = path_1.default.join(reg.contentRoot, registries_1.REGISTRY_MANIFEST_NAME);
+                diagnostics.push(`${file}: orchestrator "${orch.name}" duplicates one already declared by an earlier registry — shadowed duplicate dropped`);
+                continue;
+            }
+            seenNames.add(orch.name);
+            declared.push(orch);
+        }
+        diagnostics.push(...r.diagnostics);
+    }
+    return { declared, diagnostics };
+}
+/** Recolecta declarados y emite sus diagnosticos como warnings. Punto unico usado por
+ *  `InjectionOrchestrator.inputFor`/`statusInputFor` y por `commands/hooks/claude.ts`
+ *  para que todos permanezcan sincronizados por construccion (ver R5.1 y el bug de
+ *  staleness que motivo esta extraccion). */
+function collectAndWarn() {
+    const { declared, diagnostics } = collectDeclaredOrchestrators();
+    for (const d of diagnostics)
+        console.warn(`warning: ${d}`);
+    return declared;
+}

package/dist/tests/commands/hooks/install-symlink-fallback.test.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
-describe('hooks/install — skill symlink fallback to copy', () => {
+describe('hooks/install — symlink fallback to copy', () => {
     let tmpHome;
     let origHome;
     let origAwmHome;
@@ -40,10 +40,18 @@ describe('hooks/install — skill symlink fallback to copy', () => {
         fs_1.default.writeFileSync(path_1.default.join(hooksDir, 'run-hook.cmd'), '#!/bin/sh\n');
         fs_1.default.writeFileSync(path_1.default.join(skillDir, 'SKILL.md'), '# using-awm\n');
     }
-    it('copies the skill when symlink throws (EPERM), preserving content', () => {
+    // Historical note: using-awm.md used to be installed via fs.symlinkSync with an
+    // EPERM fallback to a plain copy — this test used to exercise that fallback.
+    // Task 6 (writeMaterializedSkill, hooks/claude.ts) replaced the symlink entirely
+    // with a materialized write (buildContext() composed markdown via fs.writeFileSync,
+    // after an unlinkSync of any prior file): the skill file never routes through
+    // fs.symlinkSync at all anymore, for any installMethod. The EPERM mock is kept
+    // here specifically to prove that irrelevance — the assertions hold even with
+    // symlinkSync forced to throw, and the explicit "never called" check documents
+    // why: there's no fallback logic left to exercise for this file.
+    it('materializes the skill file — never attempts a symlink, so EPERM on symlinkSync never affects it', () => {
         const registryRoot = path_1.default.join(tmpHome, 'registry');
         seedRegistry(registryRoot);
-        // Force symlinkSync to fail like a platform without symlink permission.
         symlinkSpy = jest.spyOn(fs_1.default, 'symlinkSync').mockImplementation(() => {
             const err = new Error('EPERM: operation not permitted, symlink');
             err.code = 'EPERM';
@@ -53,8 +61,9 @@ describe('hooks/install — skill symlink fallback to copy', () => {
         const result = installHook({ agent: 'claude-code', registryRoot, installMethod: 'copy' });
         const skillDest = path_1.default.join(result.scriptsDir, 'using-awm.md');
         expect(fs_1.default.existsSync(skillDest)).toBe(true);
-        expect(fs_1.default.lstatSync(skillDest).isSymbolicLink()).toBe(false); // it was copied, not linked
+        expect(fs_1.default.lstatSync(skillDest).isSymbolicLink()).toBe(false); // materialized, not linked
         expect(fs_1.default.readFileSync(skillDest, 'utf-8')).toContain('using-awm');
+        expect(symlinkSpy).not.toHaveBeenCalled(); // proves the EPERM mock above was moot
     });
     // Regression: syncExecutable (shared.ts) — used for the hook SCRIPT files
     // (session-start, run-hook.cmd), not just the bootstrap skill above — called