deepdebug-local-agent 1.0.22 → 1.0.23

package/README.md

@@ -0,0 +1,81 @@
+# DeepDebug Local Agent
+
+AI-powered on-prem ingestion arm of the VisionHammer / DeepDebug pipeline. The
+local agent watches application logs, surfaces incidents, and forwards them to
+the gateway for downstream analysis.
+
+- **Runtime:** Node.js 18+ (pure ESM, `"type": "module"`)
+- **Test runner:** `node:test` (Node built-in)
+- **Distribution:** `npm install` for development; `pkg`-bundled binaries for
+  production install (`npm run build:all`)
+- **Package:** `deepdebug-local-agent@1.0.21`
+
+## Quick start
+
+```bash
+npm install
+npm test           # runs node --test (52 tests across adapters + registry)
+npm start          # boots the agent (default port 5055; MCP bridge on 5056)
+```
+
+Configuration lives in `~/.deepdebug/config.json` and via env vars (`PORT`,
+`MCP_PORT`, `GATEWAY_URL`, `DEEPDEBUG_API_KEY`, `TENANT_ID`,
+`DISABLE_WS_TUNNEL`, `LEGACY_STACKS`).
+
+Companion docs:
+
+- [QUICKSTART.md](./docs/QUICKSTART.md) — end-user install + first-run
+- [ENTERPRISE_DEPLOYMENT_GUIDE.md](./docs/ENTERPRISE_DEPLOYMENT_GUIDE.md)
+- [SECURITY_WHITEPAPER.md](./docs/SECURITY_WHITEPAPER.md)
+- [docs/legacy-connectors.md](./docs/legacy-connectors.md) — **Phase 2** legacy
+  stack ingestion reference
+
+## Features
+
+- Real-time application log ingestion via `processManager.on('log', ...)`
+- AI-driven patch generation (`AIVibeCodingEngine`) wired to the gateway
+- Workspace-scoped operations via the workspace manager
+- Backup / restore with disk-indexed history
+- WebSocket reverse tunnel to the gateway (`startWebSocketTunnel`)
+- MCP HTTP bridge (`startMCPHttpServer` on port 5056)
+- **Legacy connectors** — five EventEmitter adapters for legacy on-prem stacks
+  (see below)
+
+## Legacy connectors
+
+DeepDebug Local Agent ships five EventEmitter adapters for legacy on-prem
+stacks, behind a single `LEGACY_STACKS` env var:
+
+- **SAP** (`src/adapters/sap/`) — watches SAP NetWeaver `dev_w*` work-process
+  traces + `SLOG*` system logs
+- **IBM MQ** (`src/adapters/ibmmq/`) — watches `AMQERR0[1-3].LOG` files
+- **AS/400** (`src/adapters/as400/`) — polls DSPLOG via SSH with auto-reconnect
+- **Oracle Forms** (`src/adapters/oracle-forms/`) — watches `*.trc` trace files
+  (Latin-1 tolerant)
+- **COBOL/Mainframe** (`src/adapters/cobol/`) — watches JES2 spool exports
+  (CRLF + 80-col tolerant)
+
+Each adapter emits `error` events with a frozen 6-key shape:
+`{adapter, errorCode, file, message, source, timestamp}`.
+
+To enable: set `LEGACY_STACKS=sap,cobol` (comma-separated subset of
+`sap,ibmmq,as400,oracle-forms,cobol`) in the agent's environment. When unset,
+the adapters are not loaded and the local-agent boot path is byte-for-byte
+unchanged.
+
+Full configuration + troubleshooting reference:
+[docs/legacy-connectors.md](./docs/legacy-connectors.md).
+
+## Development
+
+```bash
+npm test                 # full suite (52 tests)
+npm run sync-fixtures    # refresh test/fixtures/<stack>/ from example repos
+                         # (requires ~/.config/visionhammer/github-pat)
+npm run lint             # eslint src/
+npm run dev              # NODE_ENV=development node src/server.js
+```
+
+## License
+
+Proprietary — InspTech AI.

package/docs/legacy-connectors.md

@@ -0,0 +1,268 @@
+# Legacy connectors — configuration & troubleshooting
+
+Phase 2 of VisionHammer ships five Node.js EventEmitter adapters that ingest
+logs from legacy on-prem systems into the DeepDebug pipeline. This document is
+the operator's reference for enabling and tuning them.
+
+## Quick start
+
+1. Read [Setup](#setup) to configure your GitHub PAT (only needed if you plan to
+   run `npm run sync-fixtures` to refresh test fixtures).
+2. Set `LEGACY_STACKS=<stacks>` in the agent's environment to choose which
+   adapters boot. Example: `LEGACY_STACKS=sap,cobol`.
+3. Provide per-adapter config via env or `agent.yaml` (see
+   [Configuration](#configuration) below).
+4. Restart the local agent. Adapters start automatically and stop within 5 s on
+   `SIGTERM`.
+
+## Setup
+
+The `npm run sync-fixtures` script clones the
+`williambella/visionhammer-example-*` GitHub repos to refresh
+`test/fixtures/<stack>/` from upstream. It needs a GitHub PAT.
+
+1. On github.com → Developer settings → Personal access tokens → Tokens
+   (classic) → Generate new token. Scope: `repo` (read-only is sufficient).
+2. Save the PAT to `~/.config/visionhammer/github-pat` with permissions `0600`:
+   ```bash
+   mkdir -p ~/.config/visionhammer
+   echo "YOUR_PAT_HERE" > ~/.config/visionhammer/github-pat
+   chmod 600 ~/.config/visionhammer/github-pat
+   ```
+3. **Never paste** the PAT into a shell env var. The script reads the file
+   directly at invocation time and validates the token against `GET /user`
+   before any clone. (T-2-04 + T-2-05 mitigation.)
+
+## Configuration
+
+Adapters are configured via the `LEGACY_STACKS` env var (which stacks to boot)
+plus per-adapter env vars or `agent.yaml` entries.
+
+### Supported stacks
+
+| Stack          | Adapter dir                | Default config                                                          | Required mounts/access                                                        |
+| -------------- | -------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `sap`          | `src/adapters/sap/`        | `{sapDir: '/usr/sap/PRD', instanceNumber: '00', interval: 5000}`        | NFS/SMB mount of `/usr/sap/<SID>/` readable by the agent user                 |
+| `ibmmq`        | `src/adapters/ibmmq/`      | `{errorsDir: '/var/mqm/qmgrs/QM_PRD01/errors', interval: 5000}`         | Read access to qmgr `errors/` directory                                       |
+| `as400`        | `src/adapters/as400/`      | `{host: 'as400-prd-01', port: 22, pollInterval: 30000}`                 | SSH credentials (password OR private-key); user with `DSPLOG` authority       |
+| `oracle-forms` | `src/adapters/oracle-forms/` | `{traceDir: '/u01/oracle/forms/trace', interval: 5000}`               | Read access to `FORMS_TRACE_DIR`                                              |
+| `cobol`        | `src/adapters/cobol/`      | `{spoolDir: '/var/spool/jes2', interval: 5000}`                         | Read access to JES2 spool export dir                                          |
+
+Glob anchors (per-adapter, hard-coded):
+
+- **SAP** watches `<sapDir>/D<instanceNumber>/work/dev_w*` AND
+  `<sapDir>/D<instanceNumber>/log/SLOG*` (T-2-03 mitigation — narrow regex
+  surface).
+- **IBM MQ** watches `<errorsDir>/AMQERR*.LOG` then enforces filename anchor
+  `^AMQERR0[1-3]\.LOG$` in-handler (chokidar bracket-class workaround on macOS
+  / Node 24 / chokidar 3.6.0).
+- **Oracle Forms** watches `<traceDir>/*.trc` only (`*.log` is **not** read).
+- **COBOL** watches `<spoolDir>/*` with `depth: 0` (broad spool glob — JES2
+  exports use arbitrary file names; non-files are filtered with `isFile()`).
+- **AS/400** does NOT watch files; it polls the literal command
+  `system "DSPLOG OUTPUT(*PRINT) LOGTYPE(*MSG) MSGTYPE(*ESCAPE *NOTIFY)"` over
+  SSH every `pollInterval` ms.
+
+### Per-adapter config sub-objects
+
+The registry's
+`loadAdapters({legacyStacks, sap, ibmmq, as400, 'oracle-forms', cobol})`
+accepts one sub-object per stack. Each is passed straight to the adapter
+constructor. Override defaults by setting the corresponding key. Example:
+
+```javascript
+import { loadAdapters, stopAll } from "./src/adapters/index.js";
+
+const adapters = loadAdapters({
+  legacyStacks: ['sap', 'cobol'],
+  sap:   { sapDir: '/sapmnt/PRD', instanceNumber: '01', interval: 10000 },
+  cobol: { spoolDir: '/mnt/zos/spool', interval: 30000 },
+});
+
+for (const a of adapters) await a.start();
+// ... later, on shutdown
+await stopAll(adapters, 5000);
+```
+
+`loadAdapters` returns adapters **unstarted** (AD-1 contract). The caller owns
+the lifecycle. The `LEGACY_STACKS` env-var bootstrap path in `src/server.js`
+already wires `loadAdapters` + `start()` for you when the env var is set.
+
+## Event shape
+
+Every adapter emits `error` events with EXACTLY this shape (frozen, 6 keys, no
+extras — alphabetical key order matters for the failsafe contract test):
+
+```javascript
+{
+  adapter:   'sap' | 'ibmmq' | 'as400' | 'oracle-forms' | 'cobol',
+  errorCode: 'ORA-01403' | 'AMQ7472W' | 'CPF1234' | 'S0C7' | null,
+  file:      '/usr/sap/PRD/D00/work/dev_w0',
+  message:   '<verbatim matched line>',
+  source:    '/usr/sap/PRD/D00/work',
+  timestamp: '2024-01-15T09:12:44.000Z'
+}
+```
+
+Per AD-5, events are ordered by byte position **within a single file**.
+Cross-file and cross-adapter ordering are explicit non-guarantees — the
+downstream gateway pipeline correlates by `incidentId`, not by event sequence.
+
+`timestamp` is the moment the adapter detected the line (not the timestamp
+inside the log line — log-line timestamps have inconsistent precision across
+formats).
+
+## Sync fixtures script
+
+```bash
+# Sync all 5 stacks
+npm run sync-fixtures
+
+# Sync only a subset
+node scripts/sync-fixtures.mjs --stacks=oracle-forms,cobol
+```
+
+What it does, in order, for each requested stack:
+
+1. Reads the PAT once from `~/.config/visionhammer/github-pat`.
+2. Validates the PAT via `GET https://api.github.com/user` (T-2-05).
+3. Shallow-clones `williambella/visionhammer-example-<stack>` to
+   `/tmp/sync-<stack>` via `git clone --depth 1 --branch main` with the PAT
+   embedded in the URL **only as a `child_process.spawn` argv element**, never
+   echoed to stdout/stderr/argv-string/env (T-2-04).
+4. Copies `samples/*.log` (case-insensitive) into `test/fixtures/<dir>/`
+   (mapping: `sap-abap → sap`, `ibm-mq → ibmmq`, others identity).
+5. Renames IBM MQ fixtures so they pass the adapter's `^AMQERR0[1-3]\.LOG$`
+   filename anchor:
+
+   | Source filename                          | Target filename |
+   | ---------------------------------------- | --------------- |
+   | `ibm-mq-sample-mqrc-2033.log`            | `AMQERR01.LOG`  |
+   | `ibm-mq-sample-mqrc-2058.log`            | `AMQERR02.LOG`  |
+   | `ibm-mq-sample-resource-leak.log`        | `AMQERR03.LOG`  |
+
+6. Removes the `/tmp/sync-<stack>` clone scratch dir.
+
+Idempotent — re-runs cleanly overwrite prior fixtures and rewipe scratch dirs.
+On git failure the embedded PAT is replaced with `***REDACTED***` before
+stderr is written.
+
+## Example fixture repos
+
+| Stack             | Repo                                                                                       |
+| ----------------- | ------------------------------------------------------------------------------------------ |
+| Oracle Forms 12c  | [williambella/visionhammer-example-oracle-forms](https://github.com/williambella/visionhammer-example-oracle-forms) |
+| Oracle PL/SQL     | [williambella/visionhammer-example-plsql](https://github.com/williambella/visionhammer-example-plsql)               |
+| SAP ABAP          | [williambella/visionhammer-example-sap-abap](https://github.com/williambella/visionhammer-example-sap-abap)         |
+| COBOL / z/OS      | [williambella/visionhammer-example-cobol](https://github.com/williambella/visionhammer-example-cobol)               |
+| IBM MQ Java       | [williambella/visionhammer-example-ibm-mq](https://github.com/williambella/visionhammer-example-ibm-mq)             |
+
+Each repo carries: an intentional-bug `README.md`, source code reproducing each
+bug, `samples/<stack>-sample-<n>.log` synthetic logs, and `samples/README.md`
+with `## Source citation`, `## Product version`, and
+`## Zero PII confirmation` sections per AD-6.
+
+## Troubleshooting
+
+### CPU usage too high (T-2-01)
+
+Default poll intervals are conservative (5 s for chokidar-based adapters,
+30 s for AS/400 SSH). If you see elevated CPU on the agent host or the legacy
+system:
+
+- Increase `interval` for chokidar adapters (sap, ibmmq, oracle-forms, cobol).
+  Try `10000` (10 s) first.
+- Increase `pollInterval` for AS/400. Try `60000` (60 s).
+- Do **not** set `interval < 1000`. NFS/SMB watch polling at sub-second cadence
+  is pathological for production systems.
+
+### AS/400 SSH session keeps dropping (T-2-02)
+
+The AS/400 adapter uses SSH keepalive (`keepaliveInterval: 30000` ×
+`keepaliveCountMax: 3` = 90 s tolerance) and auto-reconnects on `'close'` with
+exponential backoff:
+
+```
+1 s → 2 s → 4 s → 8 s → 16 s → 32 s → 60 s (cap)
+```
+
+Backoff resets to 1 s on successful re-auth (`'ready'` event).
+
+To verify reconnect health: tail the agent log; `'close'` events should be
+followed by a successful `'ready'` within ~60 s. If reconnect storms occur:
+
+- Verify the AS/400 SSH server's idle timeout setting. Some SSH daemons close
+  sessions despite keepalive; tune the daemon's `ClientAliveInterval` higher
+  than 30 s.
+- Check network MTU between the agent and AS/400. Fragmented keepalive packets
+  get dropped.
+- The polling cadence (`pollInterval`, default 30 s) is independent of the
+  keepalive cadence — they run on separate timers.
+
+### `npm run sync-fixtures` fails with "GitHub credentials not configured"
+
+Confirm `~/.config/visionhammer/github-pat` exists, is readable by the agent
+user, and contains a valid PAT with `repo` scope. The script reads this file
+once at invocation; it never accepts a PAT from env vars. (T-2-04 mitigation.)
+
+### `npm run sync-fixtures` fails with "PAT validation failed"
+
+The PAT validity gate (`GET /user`) returned a non-200 status. Causes:
+
+- PAT expired or revoked. Regenerate at github.com/settings/tokens.
+- PAT lost `repo` scope. Regenerate.
+- Network failure to api.github.com. Re-run when connectivity returns.
+
+### `npm run sync-fixtures` partial failure for one stack
+
+The script aborts on first failure (per current implementation) so each clone
+gates the next. Common causes:
+
+- Repo deleted from `williambella/visionhammer-example-<stack>`. Recreate by
+  re-running Phase 2 / Plan 02-0X (where X = 2..6).
+- Stack name typo in `--stacks=`. Allowed values:
+  `oracle-forms,plsql,sap-abap,cobol,ibm-mq`.
+- Network failure mid-clone. Re-run the script.
+
+### SIGTERM doesn't shut down adapters cleanly
+
+The `SIGTERM` handler in `src/server.js` calls `stopAll(_legacyAdapters, 5000)`
+— adapters have 5 s to release file handles + close SSH. The 5-s budget is
+enforced by an `unref`'d timer racing the `Promise.all` of per-adapter
+`stop()` calls; per-adapter exceptions are swallowed so the shutdown path
+always returns.
+
+If a process refuses to exit altogether, that's a separate concern: the
+`local-agent` process keeps an `express` listener (`PORT`) and an MCP HTTP
+listener (`MCP_PORT`) open, plus an optional WebSocket reverse tunnel. Those
+are not closed by the SIGTERM handler today (pre-existing local-agent
+architecture). Set `DISABLE_WS_TUNNEL=true` to drop the WS half; the express
++ MCP listeners require a separate explicit close path.
+
+For the **legacy connector contract specifically** — `stopAll(adapters, 5000)`
+is verified to resolve within 5 s (registry contract test
+`stopAll respects timeout — slow stop does not block forever`).
+
+### Adapter logs nothing
+
+Possible causes by adapter:
+
+- **All chokidar adapters** — TAIL mode is the default. Newly-appended lines
+  emit; existing content does not. To replay a file from byte 0 set
+  `replayOnStart: true` in the adapter config.
+- **SAP / IBM MQ / Oracle Forms / COBOL** — verify the watched directory
+  exists; ENOENT is silent by design (legitimate state for newly-provisioned
+  systems).
+- **IBM MQ** — only `AMQERR01.LOG`, `AMQERR02.LOG`, `AMQERR03.LOG` are read.
+  `AMQERR04.LOG` and other names are silently dropped at the in-handler anchor
+  regex.
+- **AS/400** — verify SSH connectivity (`ssh -p 22 user@as400-prd-01 'system DSPLOG'`).
+  ENOENT-equivalent (unreachable host) shows in the agent stderr only on the
+  first `'close'` failure; subsequent reconnect attempts are silent.
+
+## Field references
+
+- 02-SPEC.md: `~/Documents/Projects/visionhammer-agents/.planning/phases/02-legacy-stack-support/02-SPEC.md`
+- Phase 3 (LegacyErrorPatterns Java catalog): consumes `test/fixtures/<stack>/`
+  as test fixtures.
+- Phase 6 (E2E smoke): re-uses the example repos as workspaces.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepdebug-local-agent",
-  "version": "1.0.22",
+  "version": "1.0.23",
   "description": "DeepDebug Local Agent - AI-powered code debugging assistant",
   "private": false,
   "type": "module",
@@ -22,6 +22,7 @@
     "docker:build": "docker build -t deepdebug/local-agent:latest .",
     "docker:push": "docker push deepdebug/local-agent:latest",
     "test": "node --test",
+    "sync-fixtures": "node scripts/sync-fixtures.mjs",
     "lint": "eslint src/"
   },
   "pkg": {
@@ -34,12 +35,14 @@
     "@anthropic-ai/sdk": "^0.39.0",
     "@modelcontextprotocol/sdk": "^1.0.4",
     "body-parser": "^1.20.3",
+    "chokidar": "^3.6.0",
     "cors": "^2.8.5",
     "express": "^4.19.2",
     "js-yaml": "^4.1.0",
     "pg": "^8.20.0",
     "pidusage": "^3.0.2",
     "properties-reader": "^2.3.0",
+    "ssh2": "^1.16.0",
     "strip-ansi": "^7.1.0",
     "unidiff": "^1.0.2",
     "ws": "^8.18.0"

package/scripts/sync-fixtures.mjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+// scripts/sync-fixtures.mjs — Phase 2 fixture sync (Plan 02-12 full implementation).
+//
+// For each requested stack, clones williambella/visionhammer-example-<stack>
+// shallow (--depth 1, --branch main) into /tmp/sync-<stack>, copies samples/
+// log files into test/fixtures/<adapter-dir>/ (with IBM MQ filename mapping),
+// then deletes the temp clone. Idempotent: re-runs cleanly overwrite prior
+// fixtures and rewipe /tmp scratch dirs.
+//
+// SECURITY (T-2-04 — PAT discipline):
+//   - PAT read ONCE from ~/.config/visionhammer/github-pat.
+//   - Embedded ONLY in `https://x-access-token:$PAT@github.com/...` URL form,
+//     passed as a `child_process.spawn` ARGV element (not a shell string), so
+//     no shell ever sees it. The argv carrying the URL IS visible to ps(1)
+//     during clone — that is the standard git-over-https risk window per AD-3.
+//   - Stdout/stderr are CAPTURED but only stack names / generic progress are
+//     written to console. Git's own stderr (which can contain the embedded
+//     URL on auth failure) is sanitised: every literal occurrence of the PAT
+//     is replaced with `***REDACTED***` before the buffer touches stderr.
+//   - The PAT NEVER goes into argv via a shell string, environment variable,
+//     log file, or thrown error message.
+//
+// SECURITY (T-2-05 — PAT scope assertion):
+//   - Before any clone, calls GitHub /user (with the PAT) to confirm the token
+//     authenticates. We do NOT enforce a specific scope here because the
+//     fine-grained-PAT scope vocabulary differs from classic-PAT scopes; a
+//     successful GET /user is sufficient to prove the token is valid and the
+//     token cannot exceed `repo`-equivalent scope per the project setup
+//     contract documented in docs/legacy-connectors.md.
+//
+// SECURITY (T-2-06 — fixture quarantine):
+//   - test/fixtures/*/ is .gitignore'd at the repo root (verified by Plan 02-01).
+//     The synced files are therefore quarantined: they NEVER enter version
+//     control of deepdebug-local-agent. AD-2 explicit submodule rejection.
+
+import {
+  readFileSync,
+  mkdirSync,
+  rmSync,
+  readdirSync,
+  copyFileSync,
+  existsSync,
+} from 'node:fs';
+import { spawn } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PAT_PATH = join(homedir(), '.config', 'visionhammer', 'github-pat');
+const ALLOWED_STACKS = ['oracle-forms', 'plsql', 'sap-abap', 'cobol', 'ibm-mq'];
+
+// Mapping: example-repo-stack name → local fixture directory name.
+// Example repos use product names (sap-abap, ibm-mq); local fixtures use
+// adapter names (sap, ibmmq). plsql has no Phase 2 adapter — fixtures are
+// synced for Phase 3 catalog work.
+const FIXTURE_DIR_MAP = Object.freeze({
+  'oracle-forms': 'oracle-forms',
+  'plsql': 'plsql',
+  'sap-abap': 'sap',
+  'cobol': 'cobol',
+  'ibm-mq': 'ibmmq',
+});
+
+// IBM MQ filename mapping (per Plan 02-08 SUMMARY's filename-mismatch decision).
+// The IbmMqLogAdapter only reads files matching `^AMQERR0[1-3]\.LOG$`. The
+// remote example repo intentionally uses descriptive sample names; sync-time
+// renaming makes the synced fixtures consumable by the adapter's contract.
+// Order is stable so re-runs always produce the same target filenames.
+const IBM_MQ_FILENAME_MAP = Object.freeze({
+  'ibm-mq-sample-mqrc-2033.log': 'AMQERR01.LOG',
+  'ibm-mq-sample-mqrc-2058.log': 'AMQERR02.LOG',
+  'ibm-mq-sample-resource-leak.log': 'AMQERR03.LOG',
+});
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(__dirname, '..');
+
+function readPat() {
+  // SECURITY: do NOT log PAT_PATH contents on error or success. ENOENT = caller missing setup.
+  try {
+    return readFileSync(PAT_PATH, 'utf8').trim();
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      process.stderr.write(
+        'sync-fixtures: GitHub credentials not configured. See docs/legacy-connectors.md.\n',
+      );
+      process.exit(2);
+    }
+    throw err;
+  }
+}
+
+function parseArgs(argv) {
+  // --stacks=oracle-forms,plsql  OR  --stacks oracle-forms plsql  OR  default = all
+  const args = argv.slice(2);
+  const flagIdx = args.findIndex((a) => a === '--stacks' || a.startsWith('--stacks='));
+  if (flagIdx === -1) return ALLOWED_STACKS;
+  const flag = args[flagIdx];
+  const raw = flag.startsWith('--stacks=')
+    ? flag.slice('--stacks='.length)
+    : (args[flagIdx + 1] || '');
+  const requested = raw.split(',').map((s) => s.trim()).filter(Boolean);
+  const unknown = requested.filter((s) => !ALLOWED_STACKS.includes(s));
+  if (unknown.length > 0) {
+    process.stderr.write(
+      `sync-fixtures: unknown stack(s): ${unknown.join(', ')}. Allowed: ${ALLOWED_STACKS.join(', ')}\n`,
+    );
+    process.exit(2);
+  }
+  return requested.length === 0 ? ALLOWED_STACKS : requested;
+}
+
+/**
+ * Run a child process; never log argv. Captures stdout/stderr buffers.
+ * @returns {Promise<{code:number, out:string, err:string}>}
+ */
+function run(cmd, args, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let out = '';
+    let err = '';
+    child.stdout.on('data', (d) => { out += d.toString(); });
+    child.stderr.on('data', (d) => { err += d.toString(); });
+    child.on('close', (code) => resolve({ code, out, err }));
+    child.on('error', reject);
+  });
+}
+
+/**
+ * T-2-05: confirm the PAT authenticates against GitHub before any clone.
+ * On failure, exit 2 with a generic message — never echo the PAT or response.
+ */
+async function assertPatValid(pat) {
+  // node:fetch is built-in on Node 18+. Authorization header is the standard
+  // PAT delivery channel — never logged, never persisted.
+  const res = await fetch('https://api.github.com/user', {
+    headers: {
+      Authorization: `Bearer ${pat}`,
+      Accept: 'application/vnd.github+json',
+      'User-Agent': 'visionhammer-sync-fixtures',
+    },
+  });
+  if (!res.ok) {
+    // Do NOT print response body — GitHub may echo parts of the request URL.
+    process.stderr.write(
+      `sync-fixtures: PAT authentication failed (HTTP ${res.status}). Verify ~/.config/visionhammer/github-pat.\n`,
+    );
+    process.exit(2);
+  }
+  // We intentionally do NOT verify scope strings — fine-grained-PAT and
+  // classic-PAT report scopes differently. Validity is sufficient per AD-3.
+}
+
+async function syncStack(stack, pat) {
+  const tmpClone = `/tmp/sync-${stack}`;
+  const repoUrl = `https://x-access-token:${pat}@github.com/williambella/visionhammer-example-${stack}.git`;
+  const fixtureDir = FIXTURE_DIR_MAP[stack];
+  const dest = join(REPO_ROOT, 'test', 'fixtures', fixtureDir);
+
+  // Clean any prior temp clone (idempotent re-runs).
+  try { rmSync(tmpClone, { recursive: true, force: true }); } catch (_) { /* ok */ }
+
+  process.stdout.write(`sync-fixtures: cloning ${stack} ... `);
+  const clone = await run(
+    'git',
+    ['clone', '--depth', '1', '--branch', 'main', repoUrl, tmpClone],
+    REPO_ROOT,
+  );
+  if (clone.code !== 0) {
+    process.stderr.write(
+      `\nsync-fixtures: git clone failed for ${stack} (exit ${clone.code}).\n`,
+    );
+    // Sanitize: replace any occurrence of the PAT with a redaction before
+    // letting git's stderr touch our stderr. Defence in depth — git rarely
+    // includes the credential portion of the URL but the redaction is cheap.
+    const sanitized = clone.err.split(pat).join('***REDACTED***');
+    process.stderr.write(sanitized + '\n');
+    return false;
+  }
+  process.stdout.write('cloned. ');
+
+  const srcSamples = join(tmpClone, 'samples');
+  if (!existsSync(srcSamples)) {
+    process.stderr.write(
+      `\nsync-fixtures: ${stack}: samples/ dir missing in repo, skipping copy.\n`,
+    );
+    try { rmSync(tmpClone, { recursive: true, force: true }); } catch (_) { /* ok */ }
+    return false;
+  }
+
+  mkdirSync(dest, { recursive: true });
+  const files = readdirSync(srcSamples).filter(
+    (f) => f.toLowerCase().endsWith('.log'),
+  );
+  let copied = 0;
+  for (const f of files) {
+    let targetName = f;
+    if (stack === 'ibm-mq') {
+      // Apply filename mapping (Plan 02-08 SUMMARY decision).
+      targetName = IBM_MQ_FILENAME_MAP[f] ?? null;
+      if (!targetName) {
+        // Sample without an explicit mapping is silently skipped — adapter
+        // would not pick it up anyway (filename anchor /^AMQERR0[1-3]\.LOG$/).
+        continue;
+      }
+    }
+    copyFileSync(join(srcSamples, f), join(dest, targetName));
+    copied++;
+  }
+  process.stdout.write(`copied ${copied} log(s) → test/fixtures/${fixtureDir}/. `);
+
+  // Cleanup temp clone.
+  try { rmSync(tmpClone, { recursive: true, force: true }); } catch (_) { /* ok */ }
+  process.stdout.write('done.\n');
+  return true;
+}
+
+async function main() {
+  const stacks = parseArgs(process.argv);
+  const pat = readPat();
+  await assertPatValid(pat); // T-2-05 gate
+  let failures = 0;
+  for (const s of stacks) {
+    const ok = await syncStack(s, pat);
+    if (!ok) failures++;
+  }
+  // PAT goes out of scope here — never persisted, never logged.
+  if (failures > 0) {
+    process.stderr.write(
+      `sync-fixtures: ${failures}/${stacks.length} stack(s) failed.\n`,
+    );
+    process.exit(1);
+  }
+  process.stdout.write(`sync-fixtures: all ${stacks.length} stack(s) synced.\n`);
+}
+
+main().catch((err) => {
+  // err.message MUST not contain PAT. We never interpolate the PAT into thrown
+  // errors anywhere above; the only thrown paths are fs/network errors whose
+  // messages do not reference the credential.
+  process.stderr.write(`sync-fixtures: fatal: ${err.message}\n`);
+  process.exit(1);
+});

package/src/adapters/as400/as400-parser.js

@@ -0,0 +1,12 @@
+// src/adapters/as400/as400-parser.js
+// OS/400 message ID prefixes: CPF (escape), MCH (machine check), SQL (DB2 for i)
+// Anchored at start-of-line so arbitrary text containing the substring
+// (e.g. "see CPF1234 docs") does not match — T-2-03-equivalent isolation surface.
+export const AS400_MSGID_REGEX = /^(CPF|MCH|SQL)(\d{4})\b/;
+
+export function extractMessageId(line) {
+  const m = line.match(AS400_MSGID_REGEX);
+  return m ? `${m[1]}${m[2]}` : null;
+}
+
+export const DSPLOG_COMMAND = 'system "DSPLOG OUTPUT(*PRINT) LOGTYPE(*MSG) MSGTYPE(*ESCAPE *NOTIFY)"';