@sabaiway/agent-workflow-kit 1.9.1 → 1.11.0

package/bin/install.test.mjs

@@ -7,11 +7,16 @@ import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { engineInstallArgv, installEngine, ENGINE_PACKAGE } from './install.mjs';
+
 const INSTALLER = join(dirname(fileURLToPath(import.meta.url)), 'install.mjs');
 const KIT_ROOT = dirname(dirname(INSTALLER));
-// --no-launchers so the test never wires Codex/Devin on the host. `extra` appends flags (e.g. --force).
+// --no-launchers so the test never wires Codex/Devin on the host; --no-engine so a full install never
+// spawns a real `npx … agent-workflow-engine init` (network + a write to the real engine dir). The
+// dedicated engine-step tests cover that path in-process / via a deliberately-broken PATH. `extra`
+// appends flags (e.g. --force, --allow-downgrade).
 const runInstaller = (target, extra = []) =>
-  spawnSync(process.execPath, [INSTALLER, '--dir', target, '--no-launchers', ...extra], { encoding: 'utf8' });
+  spawnSync(process.execPath, [INSTALLER, '--dir', target, '--no-launchers', '--no-engine', ...extra], { encoding: 'utf8' });
 
 // Rewrite / read the installed skill's frontmatter version — used to simulate "a newer kit is already
 // installed" (the stale-cache downgrade scenario). The installer reads exactly this field.
@@ -44,6 +49,21 @@ describe('kit installer — payload + symlink-traversal hardening', () => {
     assert.equal(existsSync(join(target, 'bin/install.mjs')), false);
   });
 
+  it('removes retired mirror files an older install left behind (single source of truth on upgrade)', async () => {
+    const target = join(dir, 'agent-workflow-kit');
+    // Seed a pre-3D install carrying the now-retired bundled mirror files.
+    await mkdir(join(target, 'references'), { recursive: true });
+    await mkdir(join(target, 'tools'), { recursive: true });
+    await writeFile(join(target, 'references', 'planning.md'), 'stale mirror\n');
+    await writeFile(join(target, 'tools', 'methodology-slot.md'), 'stale mirror\n');
+    const res = runInstaller(target);
+    assert.equal(res.status, 0, res.stderr);
+    assert.equal(existsSync(join(target, 'references', 'planning.md')), false, 'retired references/planning.md removed');
+    assert.equal(existsSync(join(target, 'tools', 'methodology-slot.md')), false, 'retired tools/methodology-slot.md removed');
+    assert.ok(existsSync(join(target, 'SKILL.md')), 'the real payload is still installed');
+    assert.ok(existsSync(join(target, 'references', 'contracts.md')), 'non-retired references/ content survives');
+  });
+
   it('refuses to write through a symlinked INTERMEDIATE dest component (no leak)', async () => {
     const target = join(dir, 'target');
     const evil = join(dir, 'evil');
@@ -96,7 +116,7 @@ describe('kit installer — runs through the npx bin symlink', () => {
     const shim = join(dir, 'agent-workflow-kit'); // stands in for node_modules/.bin/<name>
     await symlink(INSTALLER, shim);
     const target = join(dir, 'home', 'agent-workflow-kit');
-    const res = spawnSync(process.execPath, [shim, '--dir', target, '--no-launchers'], { encoding: 'utf8' });
+    const res = spawnSync(process.execPath, [shim, '--dir', target, '--no-launchers', '--no-engine'], { encoding: 'utf8' });
     assert.equal(res.status, 0, res.stderr);
     assert.match(res.stdout, /installed v|updated the kit/);
     assert.ok(existsSync(join(target, 'SKILL.md')), 'install through the symlink must write the payload');
@@ -211,8 +231,107 @@ describe('kit installer — stale-cache defenses (no network)', () => {
   });
 });
 
-describe('kit installer — published tarball bundles the bridges', () => {
-  it('npm pack ships bridges/<name>/ (the execution-backend skill mirrors)', () => {
+describe('kit installer — mandatory engine install dispatch (Plan 3D, in-process, no network)', () => {
+  it('engineInstallArgv: `npx @…/engine@latest init` on POSIX, `npx.cmd` on win32, no shell:true', () => {
+    const posix = engineInstallArgv('linux');
+    assert.equal(posix.command, 'npx');
+    assert.deepEqual(posix.args, [`${ENGINE_PACKAGE}@latest`, 'init']);
+    assert.equal(posix.options.shell, undefined, 'must not spawn through a shell');
+    assert.equal(engineInstallArgv('darwin').command, 'npx');
+    assert.equal(engineInstallArgv('win32').command, 'npx.cmd');
+  });
+
+  it('installEngine: first attempt succeeds → ok, runner called once (no retry)', () => {
+    let calls = 0;
+    const res = installEngine('linux', () => {
+      calls += 1;
+      return { status: 0 };
+    });
+    assert.deepEqual(res, { ok: true });
+    assert.equal(calls, 1);
+  });
+
+  const NO_SLEEP = { sleep: () => {} }; // skip the real backoff so the suite never actually waits
+
+  it('installEngine: fail once then succeed → backoff + retried exactly once, ends ok (D1)', () => {
+    let calls = 0;
+    let slept = 0;
+    const res = installEngine('linux', () => {
+      calls += 1;
+      return { status: calls === 1 ? 1 : 0 };
+    }, { sleep: () => { slept += 1; } });
+    assert.deepEqual(res, { ok: true });
+    assert.equal(calls, 2);
+    assert.equal(slept, 1, 'backoff runs exactly once, before the single retry');
+  });
+
+  it('installEngine: fails twice → not ok (D1 hard-failure outcome), no third attempt', () => {
+    let calls = 0;
+    const res = installEngine('linux', () => {
+      calls += 1;
+      return { status: 1 };
+    }, NO_SLEEP);
+    assert.deepEqual(res, { ok: false });
+    assert.equal(calls, 2);
+  });
+
+  it('installEngine: a spawn error (npx not found) counts as a failure', () => {
+    const res = installEngine('linux', () => ({ status: null, error: new Error('spawn npx ENOENT') }), NO_SLEEP);
+    assert.deepEqual(res, { ok: false });
+  });
+
+  it('installEngine: hands the runner the exact descriptor (command/args/options, no shell)', () => {
+    let received;
+    installEngine('win32', (d) => {
+      received = d;
+      return { status: 0 };
+    });
+    assert.equal(received.command, 'npx.cmd');
+    assert.deepEqual(received.args, [`${ENGINE_PACKAGE}@latest`, 'init']);
+    assert.equal(received.options.shell, undefined);
+  });
+});
+
+describe('kit installer — mandatory engine install (subprocess)', () => {
+  let dir;
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'aw-kit-engine-'));
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('--no-engine skips the engine install and prints the live-read STOP note (exit 0)', () => {
+    const target = join(dir, 'agent-workflow-kit'); // runInstaller appends --no-engine by default
+    const res = runInstaller(target);
+    assert.equal(res.status, 0, res.stderr);
+    assert.match(res.stdout, /--no-engine: skipped installing the methodology engine/);
+    assert.match(res.stdout, /@latest init/);
+    assert.match(res.stdout, /installed v|updated the kit/, 'the kit itself still installs');
+  });
+
+  it('D1: when `npx` cannot run (both attempts fail) → nonzero exit, recommendations, success block NOT printed first', async () => {
+    // Force both engine-install attempts to fail deterministically WITHOUT network: run a real install
+    // (no --no-engine) with an empty PATH so `npx` resolves to ENOENT. The kit copy + the version gate
+    // do not need PATH; only the engine spawn does. This exercises the D1 loud-error + nonzero exit.
+    const target = join(dir, 'agent-workflow-kit');
+    const emptyBin = join(dir, 'emptybin');
+    await mkdir(emptyBin, { recursive: true });
+    const res = spawnSync(process.execPath, [INSTALLER, '--dir', target, '--no-launchers'], {
+      encoding: 'utf8',
+      env: { ...process.env, PATH: emptyBin },
+    });
+    assert.notEqual(res.status, 0, 'an engine-install failure must exit nonzero');
+    assert.match(res.stderr, /FAILED to install the methodology engine/);
+    assert.match(res.stderr, /@latest init/, 'recommends the manual engine install');
+    assert.match(res.stderr, /--no-engine/, 'recommends the opt-out');
+    assert.doesNotMatch(res.stdout, /Next — open your agent/, 'must NOT claim success before the engine failed');
+    assert.ok(existsSync(join(target, 'SKILL.md')), 'the kit itself is still on disk (recovery is one step)');
+  });
+});
+
+describe('kit installer — published tarball bundles the bridges + the live-read tool', () => {
+  it('npm pack ships bridges/<name>/ and tools/engine-source.mjs', () => {
     // The real `files` whitelist decides what publishes — assert against `npm pack`, not the source
     // tree, so a dropped `bridges/` entry in package.json fails here (not silently at install time).
     const res = spawnSync('npm', ['pack', '--dry-run', '--json'], { cwd: KIT_ROOT, encoding: 'utf8' });
@@ -220,5 +339,9 @@ describe('kit installer — published tarball bundles the bridges', () => {
     const paths = JSON.parse(res.stdout)[0].files.map((f) => f.path);
     assert.ok(paths.includes('bridges/codex-cli-bridge/SKILL.md'), 'codex bridge SKILL.md not packed');
     assert.ok(paths.includes('bridges/antigravity-cli-bridge/bin/agy.sh'), 'antigravity agy.sh not packed');
+    assert.ok(paths.includes('tools/engine-source.mjs'), 'the live-read resolver must ship in the tarball');
+    // The retired mirror must NOT ship — the whole point of Plan 3D is one source of truth.
+    assert.ok(!paths.includes('tools/methodology-slot.md'), 'retired mirror tools/methodology-slot.md must not be packed');
+    assert.ok(!paths.includes('references/planning.md'), 'retired mirror references/planning.md must not be packed');
   });
 });

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "1.9.1",
+  "version": "1.11.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.9.1",
+  "version": "1.11.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/contracts.md

@@ -17,7 +17,27 @@ The user chooses at bootstrap whether the AI artifacts are visible in the repo o
 diverge:
 
 - **visible** — artifacts are committed. Wire the project's `package.json` scripts (`docs:check` / `docs:index` / `docs:index:check` / `docs:archive` / `docs:archive:check` / `docs:archive:issues` / `docs:archive:issues:check` / `prepare: node scripts/install-git-hooks.mjs`) and add a minimal `.gitignore` (`docs/plans/`, `.claude/settings.local.json`). This is the canonical model.
-- **hidden** (in-tree) — same files on disk, but the repo "looks normal": append the artifact paths (`AGENTS.md`, `CLAUDE.md`, `docs/ai/`, `docs/plans/`, `scripts/*.mjs` you added, `docs/ai/.workflow-version`) to the global excludes file git **already uses** (`git config --get core.excludesFile`); if none is set, point it at `~/.gitignore_global` (`git config --global core.excludesFile ~/.gitignore_global`) and append there. **Verify `git status` shows the artifacts as ignored** afterwards. **Do not edit `package.json`** — that is a tracked change and would leak; the pre-commit hook (always untracked in `.git/hooks/`) calls the scripts via `node scripts/<x>.mjs` directly.
+- **hidden** (in-tree) — same files on disk, but the repo "looks normal": the AI/agent footprint is git-ignored via **one managed block in the project-local `.git/info/exclude`** (resolved with `git rev-parse --git-path info/exclude` — never the machine-global `core.excludesFile`, which would affect every repo on the host; **AD-014** amends **AD-006**). The kit's `tools/hide-footprint.mjs` is the single writer: it covers `KIT_OWN_PATHS ∪ the present subset of KNOWN_FOOTPRINT` (the full footprint table below — the kit's own artifacts **and** every other AI/agent tool's files). Per path: a **tracked** file → **ASK** (an exclude does nothing for it; only `git rm --cached` un-tracks it — the tool prints that command and never runs it); an untracked path already covered by a **tracked `.gitignore`** → dropped (redundant); a **present** file whose name is generic enough to be ambiguous (`falsePositiveRisk`) → **ASK**; everything else → **hidden**. `asks` are excluded from the block unless explicitly opted in. **Verify** treats a path as hidden only when it is **untracked AND ignored by our project-local block** (or a tracked `.gitignore`) — being ignored by the global excludes does **not** count. Re-running re-derives the block wholesale (sorted/deduped) → a clean re-run is a **zero-diff** no-op. On an existing global-excludes deployment the tool **detects + reports the residual legacy machine-global block and keeps it by default** (a harmless double-ignore; the local block wins precedence); removal is the explicit `--remove-global` (it prints the removed lines as a restorable backup), which **the agent only runs after asking** — another of the user's hidden repos on the same host may rely on the same root-anchored global lines. **Do not edit `package.json`** — that is a tracked change and would leak; the pre-commit hook (always untracked in `.git/hooks/`) calls the scripts via `node scripts/<x>.mjs` directly. Windows is supported (text edit, no symlinks; CRLF preserved).
+
+**Known AI/agent footprint** (the `KNOWN_FOOTPRINT` registry in `tools/known-footprint.mjs`; this table is its human mirror, kept in sync by review — D11):
+
+| Pattern | Owner | Kind | Commit-risk name? | Note |
+|---|---|---|---|---|
+| `/.claude/skills/` | Claude Code | dir | no | local-dev skills; absorbs the AD-013 one-off |
+| `/.cursor/rules/` | Cursor | dir | no | project rule files |
+| `/.cursorrules` | Cursor (legacy) | file | **yes** | legacy single-file rules |
+| `/.codeium/` | Codeium/Windsurf | dir | no | home-scoped launchers live under `~/`, out of scope |
+| `/.windsurf/` | Windsurf (Devin) | dir | no | project config dir |
+| `/.windsurfrules` | Windsurf | file | **yes** | legacy single-file rules |
+| `/GEMINI.md` | Gemini/Antigravity | file | **yes** | context file; generic name |
+| `/.antigravity.md` | Antigravity | file | **yes** | context file |
+| `/.github/copilot-*` | GitHub Copilot | file | **yes** | one reviewed glob; covers `copilot-instructions.md` |
+| `/.aider.conf.yml` | Aider | file | no | config |
+| `/.aider.chat.history.md` | Aider | file | no | chat history |
+| `/.aider.input.history` | Aider | file | no | input history |
+| `/.continue/` | Continue | dir | no | project config dir |
+
+The kit's OWN footprint (`KIT_OWN_PATHS`) — `AGENTS.md`, `CLAUDE.md`, `docs/ai/` (subsumes the stamp), the added `scripts/*.mjs`, `docs/plans/`, `.claude/settings.local.json`, and `.claude/settings.json` (hidden-only — visible mode commits it) — is always a candidate in hidden mode.
 
 Not in this version: a fully-external hidden mode (artifacts relocated outside the repo tree).
 Deferred to a later release + migration.

package/tools/engine-source.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// Live methodology-engine source resolution — the kit reads the bounded methodology fragment
+// LIVE from the installed agent-workflow-engine (the family's one source of truth), via the same
+// `detect.installed` idiom the kit already uses to find memory (detectMemory in delegation.mjs),
+// NOT an npm `dependencies` edge (the family DAG: the kit DETECTS siblings, it never imports them).
+//
+//   resolveEngineDir({ env, home }) → { dir, source }   env override vs the ~/.claude default
+//   detectEngine(dir, { source })   → { ok, reason, dir }   runs the kit's OWN validator
+//   readEngineFragment(dir, { source }) → fragment string, or THROWS a loud install-me error
+//
+// Fail-closed: readEngineFragment never falls back to a bundled copy (there is none after the
+// mirror retirement) — when the engine is needed but absent/invalid it throws with the exact
+// remediation, so the reconcile STOPs loudly rather than silently dropping the slot (AGENTS.md:
+// no silent failures). Pure-where-possible (fs + validator injectable for tests), Node >= 18.
+
+import { statSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { validateManifest, VALID } from './manifest/validate.mjs';
+
+// The engine's detect.installed contract (agent-workflow-engine/capability.json): the env override,
+// the ~/.claude default home, the declared skill name, and the in-skill path of the live fragment.
+export const ENGINE_ENV = 'AGENT_WORKFLOW_ENGINE_DIR';
+export const EXPECTED_ENGINE_NAME = 'agent-workflow-engine';
+export const ENGINE_FRAGMENT_REL = 'references/methodology-slot.md';
+const ENGINE_DEFAULT_REL = '.claude/skills/agent-workflow-engine';
+
+const defaultStatType = (path) => {
+  try {
+    const s = statSync(path);
+    return s.isDirectory() ? 'dir' : s.isFile() ? 'file' : 'other';
+  } catch {
+    return null;
+  }
+};
+
+// Resolve the installed engine dir from the env override (if set) or the ~/.claude default,
+// mirroring the engine's `detect.installed`. `source` is load-bearing: a missing dir is reported as
+// `env-set-but-missing` ONLY when source === 'env' (the user pointed us somewhere that is not there),
+// which cannot be derived from `dir` alone.
+export const resolveEngineDir = ({ env = {}, home = '' } = {}) => {
+  const fromEnv = env[ENGINE_ENV];
+  if (typeof fromEnv === 'string' && fromEnv) return { dir: fromEnv, source: 'env' };
+  return { dir: join(home, ENGINE_DEFAULT_REL), source: 'default' };
+};
+
+// Decide whether the resolved dir is a usable methodology engine. Runs the kit's OWN validator
+// (never a candidate-shipped one), and clones detectMemory's reason ladder so each failure has a
+// distinct, actionable reason. ok only on: a dir that exists + VALID manifest + kind
+// methodology-engine + the right name + available + the live fragment file present.
+export const detectEngine = (engineDir, { source } = {}, deps = {}) => {
+  const validate = deps.validate ?? validateManifest;
+  const statType = deps.statType ?? defaultStatType;
+
+  // The dir itself must exist first — this is what lets an env-pointed-but-absent dir read as the
+  // distinct `env-set-but-missing` (validateManifest would only say "capability.json not found").
+  if (statType(engineDir) !== 'dir') {
+    const reason =
+      source === 'env'
+        ? `engine dir from ${ENGINE_ENV} is missing or not a directory (env-set-but-missing): ${engineDir}`
+        : `engine not installed at ${engineDir}`;
+    return { ok: false, reason, dir: engineDir };
+  }
+
+  // The validator does an UNGUARDED read of the candidate's SKILL.md for its version source, so a
+  // corrupt engine (e.g. SKILL.md is a directory → EISDIR) makes validateManifest THROW. Treat any
+  // validator throw as `invalid` so the failure still flows through readEngineFragment's stable
+  // "methodology engine not found/invalid" message + install command — never a raw fs error.
+  const report = (() => {
+    try {
+      return validate(engineDir);
+    } catch (err) {
+      return { result: 'invalid', errors: [`validator threw: ${err?.message ?? err}`] };
+    }
+  })();
+  const fragmentPresent = statType(join(engineDir, ENGINE_FRAGMENT_REL)) === 'file';
+  const ok =
+    report.result === VALID &&
+    report.kind === 'methodology-engine' &&
+    report.name === EXPECTED_ENGINE_NAME &&
+    report.available !== false &&
+    fragmentPresent;
+  const reason = ok
+    ? 'engine manifest valid (kind: methodology-engine) and the live fragment is present'
+    : report.result !== VALID
+      ? `engine manifest ${report.result} at ${engineDir}`
+      : report.kind !== 'methodology-engine'
+        ? `engine manifest kind "${report.kind}" is not methodology-engine`
+        : report.name !== EXPECTED_ENGINE_NAME
+          ? `engine manifest name "${report.name}" is not "${EXPECTED_ENGINE_NAME}"`
+          : report.available === false
+            ? 'engine manifest is a declared stub (available:false)'
+            : `engine fragment missing (${ENGINE_FRAGMENT_REL})`;
+  return { ok, reason, dir: engineDir };
+};
+
+// Read the bounded methodology fragment LIVE from the installed engine. Returns the fragment string
+// on the happy path; THROWS a loud Error naming the resolved dir + the reason + the exact
+// remediation on absent/invalid/unreadable — never a fallback (fail-closed). The "methodology engine
+// not found/invalid" prefix is a stable contract: the agent classifies the reconcile STOP by it
+// (distinct from the cap-skip message), so do not reword it without updating SKILL.md.
+export const readEngineFragment = (engineDir, deps = {}) => {
+  const detection = detectEngine(engineDir, { source: deps.source }, deps);
+  const installHint = `npx @sabaiway/agent-workflow-engine@latest init  (or set ${ENGINE_ENV})`;
+  if (!detection.ok) {
+    throw new Error(`methodology engine not found/invalid at ${engineDir} (${detection.reason}) — install it: ${installHint}`);
+  }
+  const read = deps.readFileSync ?? readFileSync;
+  try {
+    return read(join(engineDir, ENGINE_FRAGMENT_REL), 'utf8');
+  } catch (err) {
+    throw new Error(
+      `methodology engine not found/invalid at ${engineDir} (fragment unreadable: ${err.message}) — install it: ${installHint}`,
+    );
+  }
+};

package/tools/engine-source.test.mjs

@@ -0,0 +1,182 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { join } from 'node:path';
+import {
+  resolveEngineDir,
+  detectEngine,
+  readEngineFragment,
+  ENGINE_ENV,
+  EXPECTED_ENGINE_NAME,
+  ENGINE_FRAGMENT_REL,
+} from './engine-source.mjs';
+
+// A valid engine dir = it exists (dir), the fragment file exists, and the validator reports a
+// VALID methodology-engine with the right name. The deps below let every branch be exercised
+// in-process without touching the real filesystem.
+const ENGINE_DIR = '/home/u/.claude/skills/agent-workflow-engine';
+
+// statType stub: ENGINE_DIR → 'dir', the fragment → 'file', everything else → null.
+const okStatType = (path) =>
+  path === ENGINE_DIR ? 'dir' : path === join(ENGINE_DIR, ENGINE_FRAGMENT_REL) ? 'file' : null;
+
+const okReport = {
+  result: 'valid',
+  kind: 'methodology-engine',
+  name: EXPECTED_ENGINE_NAME,
+  available: true,
+};
+
+const deps = (overrides = {}) => ({
+  validate: () => okReport,
+  statType: okStatType,
+  ...overrides,
+});
+
+describe('resolveEngineDir — env override vs the ~/.claude default', () => {
+  it('uses AGENT_WORKFLOW_ENGINE_DIR when set, tagging source=env', () => {
+    const out = resolveEngineDir({ env: { [ENGINE_ENV]: '/custom/engine' }, home: '/home/u' });
+    assert.deepEqual(out, { dir: '/custom/engine', source: 'env' });
+  });
+  it('falls back to ~/.claude/skills/agent-workflow-engine, tagging source=default', () => {
+    const out = resolveEngineDir({ env: {}, home: '/home/u' });
+    assert.equal(out.source, 'default');
+    assert.equal(out.dir, join('/home/u', '.claude/skills/agent-workflow-engine'));
+  });
+  it('treats an empty env value as unset (source=default)', () => {
+    const out = resolveEngineDir({ env: { [ENGINE_ENV]: '' }, home: '/home/u' });
+    assert.equal(out.source, 'default');
+  });
+});
+
+describe('detectEngine — happy path + each distinct failure reason', () => {
+  it('ok when dir exists, manifest VALID methodology-engine, right name, fragment present', () => {
+    const out = detectEngine(ENGINE_DIR, { source: 'default' }, deps());
+    assert.equal(out.ok, true);
+    assert.equal(out.dir, ENGINE_DIR);
+    assert.match(out.reason, /methodology-engine/);
+  });
+
+  it('env-set-but-missing: dir absent AND source=env → distinct reason', () => {
+    const out = detectEngine(ENGINE_DIR, { source: 'env' }, deps({ statType: () => null }));
+    assert.equal(out.ok, false);
+    assert.match(out.reason, /env-set-but-missing/);
+  });
+
+  it('not-installed: dir absent AND source=default → not an env-set reason', () => {
+    const out = detectEngine(ENGINE_DIR, { source: 'default' }, deps({ statType: () => null }));
+    assert.equal(out.ok, false);
+    assert.match(out.reason, /not installed/i);
+    assert.doesNotMatch(out.reason, /env-set-but-missing/);
+  });
+
+  it('invalid manifest → reason names the validator result', () => {
+    const out = detectEngine(ENGINE_DIR, { source: 'default' }, deps({ validate: () => ({ ...okReport, result: 'invalid' }) }));
+    assert.equal(out.ok, false);
+    assert.match(out.reason, /invalid/);
+  });
+
+  it('wrong kind → reason names the kind', () => {
+    const out = detectEngine(ENGINE_DIR, { source: 'default' }, deps({ validate: () => ({ ...okReport, kind: 'memory-substrate' }) }));
+    assert.equal(out.ok, false);
+    assert.match(out.reason, /kind/);
+  });
+
+  it('wrong name → reason names the name mismatch', () => {
+    const out = detectEngine(ENGINE_DIR, { source: 'default' }, deps({ validate: () => ({ ...okReport, name: 'something-else' }) }));
+    assert.equal(out.ok, false);
+    assert.match(out.reason, /name/);
+  });
+
+  it('declared stub (available:false) → reason names the stub', () => {
+    const out = detectEngine(ENGINE_DIR, { source: 'default' }, deps({ validate: () => ({ ...okReport, available: false }) }));
+    assert.equal(out.ok, false);
+    assert.match(out.reason, /stub|available:false/);
+  });
+
+  it('missing fragment → reason names the fragment path', () => {
+    const out = detectEngine(ENGINE_DIR, { source: 'default' }, deps({ statType: (p) => (p === ENGINE_DIR ? 'dir' : null) }));
+    assert.equal(out.ok, false);
+    assert.match(out.reason, /fragment/);
+  });
+
+  it('a validator that THROWS (corrupt engine, e.g. EISDIR) → ok:false, no raw error escapes', () => {
+    const out = detectEngine(
+      ENGINE_DIR,
+      { source: 'default' },
+      deps({
+        validate: () => {
+          throw new Error('EISDIR: illegal operation on a directory, read');
+        },
+      }),
+    );
+    assert.equal(out.ok, false);
+    assert.match(out.reason, /invalid/);
+  });
+});
+
+describe('readEngineFragment — live read or loud throw', () => {
+  it('returns the fragment bytes on the happy path', () => {
+    const out = readEngineFragment(ENGINE_DIR, deps({ source: 'default', readFileSync: () => 'FRAGMENT BODY' }));
+    assert.equal(out, 'FRAGMENT BODY');
+  });
+
+  it('throws naming the dir + the exact install command when the engine is absent', () => {
+    assert.throws(
+      () => readEngineFragment(ENGINE_DIR, deps({ source: 'env', statType: () => null })),
+      (err) => {
+        assert.match(err.message, /methodology engine not found\/invalid/);
+        assert.match(err.message, new RegExp(ENGINE_DIR.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+        assert.match(err.message, /npx @sabaiway\/agent-workflow-engine@latest init/);
+        assert.match(err.message, new RegExp(ENGINE_ENV));
+        return true;
+      },
+    );
+  });
+
+  it('throws when the manifest is invalid (never falls back)', () => {
+    assert.throws(
+      () => readEngineFragment(ENGINE_DIR, deps({ source: 'default', validate: () => ({ ...okReport, result: 'invalid' }) })),
+      /methodology engine not found\/invalid/,
+    );
+  });
+
+  it('a THROWING validator still yields the stable install message (no raw fs error escapes)', () => {
+    assert.throws(
+      () =>
+        readEngineFragment(
+          ENGINE_DIR,
+          deps({
+            source: 'default',
+            validate: () => {
+              throw new Error('EISDIR: illegal operation on a directory, read');
+            },
+          }),
+        ),
+      (err) => {
+        assert.match(err.message, /methodology engine not found\/invalid/);
+        assert.match(err.message, /npx @sabaiway\/agent-workflow-engine@latest init/);
+        return true;
+      },
+    );
+  });
+
+  it('throws with the install command when the fragment file is unreadable', () => {
+    assert.throws(
+      () =>
+        readEngineFragment(
+          ENGINE_DIR,
+          deps({
+            source: 'default',
+            readFileSync: () => {
+              throw new Error('EISDIR');
+            },
+          }),
+        ),
+      (err) => {
+        assert.match(err.message, /fragment unreadable: EISDIR/);
+        assert.match(err.message, /npx @sabaiway\/agent-workflow-engine@latest init/);
+        return true;
+      },
+    );
+  });
+});

package/tools/fs-safe.mjs

@@ -44,7 +44,10 @@ export const assertContainedRealPath = (root, dest, deps = {}) => {
   const lstat = deps.lstat ?? lstatSync;
   const ln = (p) => lstatNoFollow(p, lstat);
   const rel = relative(root, dest);
-  if (rel.startsWith('..') || isAbsolute(rel)) {
+  // A true escape is `..` exactly or a `..`-prefixed PATH SEGMENT (`../x`) — NOT any string starting
+  // with the two chars "..": a legitimately-contained child literally named `..foo` has rel `..foo`,
+  // which the old `rel.startsWith('..')` wrongly rejected (Issue-004 — same fix as the engine/memory installers).
+  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
     throw new Error(`[agent-workflow-kit] refusing to write outside the target dir: ${dest}`);
   }
   if (ln(root)?.isSymbolicLink()) {

package/tools/fs-safe.test.mjs

@@ -30,6 +30,12 @@ describe('assertContainedRealPath', () => {
     assert.throws(() => assertContainedRealPath('/root', '/etc/passwd'), /outside/);
   });
 
+  it('Issue-004: accepts a contained child literally named "..foo", still rejects a true ".." segment', () => {
+    // rel "..foo" is a real child, NOT a "../" escape — the old `rel.startsWith('..')` wrongly rejected it.
+    assert.doesNotThrow(() => assertContainedRealPath(dir, join(dir, '..foo')));
+    assert.throws(() => assertContainedRealPath(dir, join(dir, '..', 'escape')), /outside/);
+  });
+
   it('rejects writing INTO a symlinked root', () => {
     const real = join(dir, 'real');
     const root = join(dir, 'root');