@aiwg/cli 2026.10.10 → 2026.10.11

package/dist/src/config/worker-context.js

@@ -0,0 +1,337 @@
+/**
+ * Worker AIWG context providers and launch-time bootstrap ensure (#3685).
+ *
+ * Orchestration must automatically `aiwg use` the providers configured for
+ * it, so any new worker process starts with the AIWG bootstrap in place.
+ * This module owns the config-side half: resolving WHICH providers
+ * (config `providers` plus every CLI configured under
+ * `parallelism.clis` / `parallelism.groups.*.members`, mapped through the
+ * provider registry) and checking/ensuring that bootstrap inside exactly
+ * one worker workdir (never outside it).
+ *
+ * The tools/ half (`tools/ralph-external/lib/worker-context.mjs`) loads the
+ * config through `readAiwgConfig` and injects it here; direct callers may
+ * pass an already-loaded config object instead.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { getProviderArtifactPathStrings, getProviderDefinition, normalizeProviderDefinitionId, } from '../providers/provider-definitions.js';
+import { emptyConfig, readAiwgConfig, writeAiwgConfig, } from './aiwg-config.js';
+/**
+ * Typed refusal when a worker's AIWG bootstrap cannot be ensured.
+ * `remedy` names the operator action that unblocks the launch.
+ */
+export class WorkerContextBootstrapError extends Error {
+    code = 'OG_WORKER_CONTEXT_UNAVAILABLE';
+    remedy;
+    provider;
+    workdir;
+    constructor(message, remedy, opts) {
+        super(message);
+        this.name = 'WorkerContextBootstrapError';
+        this.remedy = remedy;
+        if (opts?.provider !== undefined)
+            this.provider = opts.provider;
+        if (opts?.workdir !== undefined)
+            this.workdir = opts.workdir;
+    }
+}
+/** Explicit provider lists must be non-empty arrays of deployable ids. */
+export function validateExplicitWorkerContextProviders(providers) {
+    if (!Array.isArray(providers) || providers.length === 0
+        || providers.some(p => typeof p !== 'string' || p.length === 0 || p.includes('\0') || p.includes(','))) {
+        throw new WorkerContextBootstrapError('worker context providers must be a non-empty array of provider ids', 'pass an explicit non-empty provider list, or configure providers plus orchestration CLIs in .aiwg/aiwg.config');
+    }
+    return [...new Set(providers)];
+}
+const ADAPTER_REFERENCE = /^(providers|workerAdapters):([a-z][a-z0-9-]{0,62})$/;
+/**
+ * Map one orchestration CLI id to its AIWG provider id.
+ * A CLI without an explicit `parallelism.clis` entry defaults to
+ * `providers:<cli>` (the same default `resolveWorkerGroupInstallation`
+ * applies). Non-provider adapters (e.g. `workerAdapters:local-http`) and
+ * ids the registry does not know are reported as skipped, never guessed.
+ */
+export function mapCliToProviderId(cli, parallelism) {
+    if (typeof cli !== 'string' || cli.length === 0) {
+        return { skipped: `empty CLI reference` };
+    }
+    const raw = typeof parallelism?.clis?.[cli]?.adapter === 'string'
+        && parallelism.clis[cli].adapter.length > 0
+        ? parallelism.clis[cli].adapter
+        : `providers:${cli}`;
+    const match = ADAPTER_REFERENCE.exec(raw);
+    if (!match || match[1] !== 'providers') {
+        return { skipped: `clis/${cli}: ${raw}` };
+    }
+    const provider = normalizeProviderDefinitionId(match[2]);
+    if (!provider)
+        return { skipped: `clis/${cli}: ${raw} (unknown provider)` };
+    return { provider };
+}
+/**
+ * Resolve the full worker-context provider set: the union of the config's
+ * own `providers` and every CLI configured for orchestration
+ * (`parallelism.clis` keys/adapters and the `cli` of every
+ * `parallelism.groups.*.members[]`), mapped to AIWG provider ids through
+ * the provider registry. Non-provider adapters are skipped and reported.
+ * Fails closed when the union is empty.
+ */
+export function resolveWorkerContextProvidersFromConfig(config) {
+    const providers = [];
+    const skipped = [];
+    const add = (id) => {
+        if (!providers.includes(id))
+            providers.push(id);
+    };
+    const skip = (entry) => {
+        if (!skipped.includes(entry))
+            skipped.push(entry);
+    };
+    const configured = config?.providers;
+    if (Array.isArray(configured)) {
+        for (const entry of configured) {
+            if (typeof entry !== 'string' || entry.length === 0)
+                continue;
+            // Configured providers deploy verbatim when the registry does not
+            // know them: project-local provider adapters resolve at deploy time
+            // (see the `use` handler's project-local resolution), so an unknown
+            // id here is the deployer's decision, not this resolver's.
+            add(normalizeProviderDefinitionId(entry) ?? entry);
+        }
+    }
+    const parallelism = config?.parallelism;
+    for (const cli of Object.keys(parallelism?.clis ?? {})) {
+        const mapped = mapCliToProviderId(cli, parallelism);
+        if ('provider' in mapped)
+            add(mapped.provider);
+        else
+            skip(mapped.skipped);
+    }
+    for (const [groupId, group] of Object.entries(parallelism?.groups ?? {})) {
+        for (const member of group?.members ?? []) {
+            const cli = member?.cli;
+            const mapped = mapCliToProviderId(cli, parallelism);
+            if ('provider' in mapped)
+                add(mapped.provider);
+            else
+                skip(typeof cli === 'string' && cli ? `groups/${groupId}/members cli '${cli}': ${mapped.skipped}` : `groups/${groupId}/members: ${mapped.skipped}`);
+        }
+    }
+    if (providers.length === 0) {
+        throw new WorkerContextBootstrapError('worker context deployment needs configured providers: the union of config providers and orchestration CLIs is empty'
+            + (skipped.length > 0 ? ` (skipped: ${skipped.join('; ')})` : ''), 'configure providers and/or parallelism clis/groups in .aiwg/aiwg.config, or pass an explicit provider list');
+    }
+    return { providers, skipped };
+}
+/** AIWG-managed rule-section markers written into a deployed AGENTS.md. */
+const WORKER_CONTEXT_RULE_MARKER = /<!--\s*AIWG:[A-Za-z0-9_-]+:(start|end)\s*-->/;
+/**
+ * Check that a worker workdir already carries one provider's bootstrap:
+ * the kernel artifact dirs (`use all` writes kernel skills, rules,
+ * behaviors — never the full agent/command surface) and, for providers
+ * whose contract targets AGENTS.md, the AIWG rule sections.
+ */
+export function workerContextBootstrapStatus({ workdir, provider }) {
+    const missing = [];
+    const definition = getProviderDefinition(provider);
+    if (!definition) {
+        return { present: false, missing: [`unknown provider '${provider}'`] };
+    }
+    const paths = getProviderArtifactPathStrings(provider);
+    const kernelDirs = [
+        definition.paths.kernelSkills,
+        paths?.rules ?? null,
+        paths?.behaviors ?? null,
+    ].filter((dir) => typeof dir === 'string' && dir.length > 0);
+    const requiredDirs = kernelDirs.length > 0
+        ? kernelDirs
+        : Object.values(paths ?? {}).filter((dir) => typeof dir === 'string' && dir.length > 0);
+    for (const dir of [...new Set(requiredDirs)]) {
+        const absolute = path.isAbsolute(dir) ? dir : path.join(workdir, dir);
+        let entries = null;
+        try {
+            entries = readdirSync(absolute);
+        }
+        catch {
+            entries = null;
+        }
+        if (!entries || entries.length === 0)
+            missing.push(`provider dir '${dir}'`);
+    }
+    if ((definition.context?.bootstrapTargets ?? []).includes('AGENTS.md')) {
+        let content = null;
+        try {
+            content = readFileSync(path.join(workdir, 'AGENTS.md'), 'utf8');
+        }
+        catch {
+            content = null;
+        }
+        if (!content || !WORKER_CONTEXT_RULE_MARKER.test(content)) {
+            missing.push('AGENTS.md rule sections');
+        }
+    }
+    return { present: missing.length === 0, missing };
+}
+/**
+ * Materialize the union provider set into the worker workdir's own config
+ * through the existing loader/writer (never ad-hoc JSON). Existing entries
+ * keep their order; union members absent from the worktree base are
+ * appended. A missing config is created minimal. An already-current config
+ * is left untouched so the deploy below stays the only writer.
+ */
+export async function syncWorkerContextProviders(options) {
+    const { workdir } = options;
+    if (typeof workdir !== 'string' || !path.isAbsolute(workdir)) {
+        throw new WorkerContextBootstrapError(`worker context sync needs an absolute workdir, got ${JSON.stringify(workdir)}`, 'sync worker context providers only into the worker workdir', { workdir: typeof workdir === 'string' ? workdir : undefined });
+    }
+    const providers = validateExplicitWorkerContextProviders(options.providers);
+    const read = options.readConfig ?? ((dir) => readAiwgConfig(dir));
+    const existing = await read(workdir);
+    const current = Array.isArray(existing?.providers)
+        ? existing.providers.filter((entry) => typeof entry === 'string')
+        : [];
+    const merged = [...current];
+    for (const provider of providers) {
+        if (!merged.includes(provider))
+            merged.push(provider);
+    }
+    const unchanged = merged.length === current.length && merged.every((entry, index) => entry === current[index]);
+    if (unchanged)
+        return { providers: merged, updated: false };
+    const base = existing !== null && typeof existing === 'object' && 'version' in existing
+        ? existing
+        : {};
+    const next = { ...emptyConfig(merged), ...base, providers: merged };
+    const write = options.writeConfig ?? ((dir, config) => writeAiwgConfig(dir, config));
+    await write(workdir, next);
+    return { providers: merged, updated: true };
+}
+/**
+ * Canonical one-pass deploy argv: a single `aiwg use all` invocation
+ * covering every listed provider. Never one deploy per provider:
+ * per-provider invocations rewrite AGENTS.md piecemeal and clobber each
+ * other's rule sections, while one pass keeps them all. No `--providers`
+ * flag: it feeds only the global bootstrap and the orchestrated
+ * verification report — `executeCore` resolves project-scope providers
+ * from config (`src/cli/handlers/use.ts`), ignoring both the flag and any
+ * explicitly resolved list. The supported project-scope mechanism is the
+ * configured-provider path: `syncWorkerContextProviders` first, then this
+ * single pass reads the union back from the worktree config.
+ */
+export function buildWorkerContextDeployArgs({ providers, target }) {
+    // Fail fast on a hostile list; the synced worktree config carries the set.
+    validateExplicitWorkerContextProviders(providers);
+    return ['use', 'all', '--target', target, '--yes'];
+}
+/**
+ * Ensure a worker workdir carries its CLI's AIWG bootstrap before launch.
+ * Present: no-op. Missing: sync the union set into the workdir config,
+ * then exactly one `aiwg use all` pass into the workdir (never anywhere
+ * else), then re-verify. Impossible (no binary, failed deploy, still
+ * missing afterwards): throw `WorkerContextBootstrapError` naming the
+ * remedy — the caller refuses the launch rather than starting a
+ * context-free worker.
+ */
+export async function ensureWorkerContextBootstrap(options) {
+    const { workdir, provider, aiwgBin = process.env.AIWG_BIN ?? 'aiwg', spawn = spawnSync, timeoutMs = 300000, statusFn = workerContextBootstrapStatus, } = options;
+    if (typeof workdir !== 'string' || !path.isAbsolute(workdir) || !existsSync(workdir)) {
+        throw new WorkerContextBootstrapError(`worker context bootstrap needs an existing absolute workdir, got ${JSON.stringify(workdir)}`, 'launch the worker with its resolved absolute workdir', { provider, workdir: typeof workdir === 'string' ? workdir : undefined });
+    }
+    const status = statusFn({ workdir, provider });
+    if (status.present)
+        return { ensured: false, providers: [provider], skippedBridges: [] };
+    const providers = options.providers && options.providers.length > 0
+        ? validateExplicitWorkerContextProviders(options.providers)
+        : [provider];
+    // The configured-provider path: the single pass below resolves its set
+    // from the workdir config, so the union must be materialized there
+    // first — `--providers` never reaches project-scope deploys.
+    const sync = options.syncFn ?? syncWorkerContextProviders;
+    let synced;
+    try {
+        synced = await sync({ workdir, providers });
+    }
+    catch (error) {
+        if (error instanceof WorkerContextBootstrapError)
+            throw error;
+        throw new WorkerContextBootstrapError(`worker context sync failed: ${error instanceof Error ? error.message : String(error)}`, `write the union providers into ${path.join(workdir, '.aiwg', 'aiwg.config')} (or run 'aiwg use all --target ${workdir} --yes' manually) before launch`, { provider, workdir });
+    }
+    const argv = buildWorkerContextDeployArgs({ providers: synced.providers, target: workdir });
+    const deploy = options.deployFn ?? (({ worktreePath, providers: deployProviders, aiwgBin: bin }) => {
+        // worktreePath IS the worker workdir by construction: the only
+        // `--target` ever passed is `workdir` above, and the spawn cwd is the
+        // same directory, so no deploy write can land outside it.
+        if (path.resolve(worktreePath) !== path.resolve(workdir)) {
+            throw new WorkerContextBootstrapError(`refusing worker context deploy outside the worker workdir (${worktreePath} !== ${workdir})`, 'deploy worker context only into the worker workdir', { provider, workdir });
+        }
+        const result = spawn(bin, argv, { cwd: workdir, encoding: 'utf8', timeout: timeoutMs });
+        if (result.error) {
+            throw new WorkerContextBootstrapError(`worker context deploy failed to run (${result.error?.message});`
+                + ` missing in ${workdir}: ${status.missing.join('; ')}`, `install the aiwg CLI on PATH or set AIWG_BIN to its location (tried '${bin}'),`
+                + ` or run 'aiwg ${argv.join(' ')}' manually before launch`, { provider, workdir });
+        }
+        if (result.status !== 0) {
+            throw new WorkerContextBootstrapError(`worker context deploy exited ${result.status}: ${String(result.stderr ?? '').trim().slice(0, 2000)};`
+                + ` missing in ${workdir}: ${status.missing.join('; ')}`, `run 'aiwg ${argv.join(' ')}' manually and resolve the reported failure before launch`, { provider, workdir });
+        }
+        return { providers: [...deployProviders] };
+    });
+    let deployed;
+    try {
+        deployed = await deploy({ worktreePath: workdir, providers: synced.providers, aiwgBin });
+    }
+    catch (error) {
+        if (error instanceof WorkerContextBootstrapError)
+            throw error;
+        throw new WorkerContextBootstrapError(`worker context deploy failed: ${error instanceof Error ? error.message : String(error)};`
+            + ` missing in ${workdir}: ${status.missing.join('; ')}`, `run 'aiwg ${argv.join(' ')}' manually and resolve the reported failure before launch`, { provider, workdir });
+    }
+    const after = statusFn({ workdir, provider });
+    if (!after.present) {
+        throw new WorkerContextBootstrapError(`worker context deploy did not produce the bootstrap: still missing in ${workdir}: ${after.missing.join('; ')}`, `run 'aiwg ${argv.join(' ')}' manually and verify the provider bootstrap before launch`, { provider, workdir });
+    }
+    // Keep deploy-touched tracked bridges out of the worker diff. A workdir
+    // outside any git repository has no tracked files; skip silently there.
+    let skippedBridges = [];
+    if (options.skipWorktreeFn) {
+        skippedBridges = options.skipWorktreeFn({ workdir });
+    }
+    else {
+        try {
+            skippedBridges = flagDeployDirtiedSkipWorktree({ workdir, spawn, timeoutMs });
+        }
+        catch {
+            skippedBridges = [];
+        }
+    }
+    return { ensured: true, providers: [...deployed.providers], skippedBridges };
+}
+/** Tracked files the deploy modified, hidden from the worker diff. */
+export function flagDeployDirtiedSkipWorktree({ workdir, spawn = spawnSync, timeoutMs = 30000 }) {
+    const status = spawn('git', ['status', '--porcelain=v1', '--untracked-files=no'], { cwd: workdir, encoding: 'utf8', timeout: timeoutMs });
+    if (status.error)
+        throw new Error(`git status failed: ${status.error?.message}`);
+    if (status.status !== 0)
+        throw new Error(`git status exited ${status.status}`);
+    const files = [];
+    for (const line of String(status.stdout ?? '').split('\n')) {
+        if (!line.trim())
+            continue;
+        const raw = line.slice(3);
+        const arrow = raw.indexOf(' -> ');
+        const rel = arrow >= 0 ? raw.slice(arrow + 4) : raw;
+        if (!rel || rel.startsWith('"'))
+            throw new Error(`worker context deploy dirtied an unflaggeable path: ${line}`);
+        files.push(rel);
+    }
+    if (files.length > 0) {
+        const flag = spawn('git', ['update-index', '--skip-worktree', '--', ...files], { cwd: workdir, encoding: 'utf8', timeout: timeoutMs });
+        if (flag.error || flag.status !== 0) {
+            throw new Error(`git update-index --skip-worktree failed: ${flag.error?.message ?? String(flag.stderr ?? '').trim()}`);
+        }
+    }
+    return files;
+}
+//# sourceMappingURL=worker-context.js.map

package/dist/src/mcp/tools/worker-invoke.mjs

@@ -178,6 +178,13 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { mcpError, mcpJson } from '../helpers.mjs';
 import { buildShellStopControl, waitForUnitTermination } from './worker-shell-control.mjs';
 import { launchPreparedShellWorker, sweepWorkerStdin } from './worker-stdin-runtime.mjs';
+// NOTE: no static import of ../../config/worker-context.js here. That
+// module is TypeScript: a literal relative import resolves under vitest
+// but throws ERR_MODULE_NOT_FOUND under raw node (e.g. `node
+// src/mcp/cli.mjs`, which test/unit/mcp exercises directly). The
+// request-time loader below resolves it through importImpl (dist when
+// built, source otherwise), so merely loading this bridge never touches
+// it. See tools/_resolve-impl.mjs (#3062).
 
 const execFileAsync = promisify(execFile);
 
@@ -642,6 +649,64 @@ function describeGateFailures(failures) {
   return `worker dispatch gate blocked: ${failures.map(f => `${f.signal} (${f.reason})`).join('; ')}`;
 }
 
+/** Request-time loader for the TypeScript worker-context module (see the
+ * import note above): resolved through importImpl so production uses the
+ * compiled `dist` tree while a checkout falls back to source. Cached for
+ * the process lifetime; only request paths that actually ensure worker
+ * context ever trigger the load. */
+let cachedWorkerContextModule = null;
+async function loadWorkerContextModule() {
+  if (!cachedWorkerContextModule) cachedWorkerContextModule = await importImpl('config/worker-context.js');
+  return cachedWorkerContextModule;
+}
+
+/** Map the worker CLI to its provider and ensure its bootstrap is present
+ * in the worker workdir (#3685 round 2). Deploys the resolved union set
+ * (config providers plus orchestration CLIs) in one pass when the worker
+ * provider's bootstrap is missing; an unmappable CLI refuses with the
+ * typed diagnostic, since no deploy could target it. */
+async function ensureWorkerContextForInvocation({ invocation, config }) {
+  const { ensureWorkerContextBootstrap, mapCliToProviderId, resolveWorkerContextProvidersFromConfig, WorkerContextBootstrapError } =
+    await loadWorkerContextModule();
+  const cli = invocation?.selected?.cli;
+  const mapped = mapCliToProviderId(cli, config?.parallelism);
+  if (!('provider' in mapped) || !mapped.provider) {
+    throw new WorkerContextBootstrapError(
+      `cannot ensure worker context: CLI '${cli}' maps to no AIWG provider (${mapped.skipped ?? 'unmapped'})`,
+      `configure parallelism.clis.${cli} with a providers:<id> adapter, or dispatch a CLI whose adapter maps to a known provider`,
+      { workdir: invocation?.cwd },
+    );
+  }
+  let providers = [mapped.provider];
+  try {
+    providers = [...new Set([...resolveWorkerContextProvidersFromConfig(config).providers, mapped.provider])];
+  } catch {
+    providers = [mapped.provider];
+  }
+  return ensureWorkerContextBootstrap({ workdir: invocation?.cwd, provider: mapped.provider, providers });
+}
+
+/** Refuse a failed bootstrap ensure as a typed blocked diagnostic that
+ * names the remedy — never a bare string the operator cannot act on.
+ * `code`/`remedy`/`provider`/`workdir` survive on any error object that
+ * carries them (the tools-side ensure throws a duck-typed refusal, not
+ * necessarily this module's class instance); only genuinely bare failures
+ * fall back to the generic code and remedy. */
+function toWorkerContextDiagnostic(error) {
+  const fields = (error !== null && typeof error === 'object') ? error : {};
+  // Duck-typed on purpose: the worker-context module loads lazily (see
+  // above), so no class identity is available at module scope. Every
+  // refusal path sets `code`/`remedy` on the thrown object instead.
+  const code = (typeof fields.code === 'string' && fields.code ? fields.code : 'OG_WORKER_CONTEXT_UNAVAILABLE');
+  const remedy = (typeof fields.remedy === 'string' && fields.remedy ? fields.remedy
+    : 'ensure the worker CLI maps to a known AIWG provider and the aiwg CLI is installed (AIWG_BIN), then retry the run');
+  return { code,
+    message: error instanceof Error ? error.message : String(error?.message ?? error),
+    remedy,
+    ...(fields.provider !== undefined ? { provider: fields.provider } : {}),
+    ...(fields.workdir !== undefined ? { workdir: fields.workdir } : {}) };
+}
+
 // Audited observer; refresh the historical baseline graph after rebase.
 const waitForUnitTerminationBaseline = waitForUnitTermination;
 export { waitForUnitTerminationBaseline as __testOnlyWaitForUnitTerminationBaseline };
@@ -758,6 +823,7 @@ export class ChildProcessTransport {
     // cap since a long-lived connection could otherwise grow it unbounded.
     this._rawResponses = new Map();
     this._buffer = undefined;
+    this._bufferBytes = 0;
   }
 
   async start() {
@@ -769,7 +835,7 @@ export class ChildProcessTransport {
       try {
         // Check each frame BEFORE concatenation or UTF-8 decoding.
         let offset = 0;
-        let frameBytes = this._buffer?.length ?? 0;
+        let frameBytes = this._bufferBytes;
         while (offset < chunk.length) {
           const newline = chunk.indexOf(10, offset);
           const end = newline === -1 ? chunk.length : newline;
@@ -782,8 +848,7 @@ export class ChildProcessTransport {
           frameBytes = 0;
           offset = newline + 1;
         }
-        this._buffer = this._buffer ? Buffer.concat([this._buffer, chunk]) : chunk;
-        this._drain();
+        this._drain(chunk);
       } catch (error) { this.onerror?.(error); }
     });
     child.stdout?.on('error', error => this.onerror?.(error));
@@ -799,6 +864,7 @@ export class ChildProcessTransport {
     if (this._closed) return;
     this._closed = true;
     this._buffer = undefined;
+    this._bufferBytes = 0;
     this._rawResponses.clear();
     this.onclose?.();
   }
@@ -807,6 +873,7 @@ export class ChildProcessTransport {
     if (this._failure) return;
     this._failure = Object.assign(new Error(code), { code });
     this._buffer = undefined;
+    this._bufferBytes = 0;
     this._rawResponses.clear();
     // Start stopping before pipe closure can exit the leader; onclose rejects
     // pending SDK requests immediately while termination proof is awaited.
@@ -825,14 +892,26 @@ export class ChildProcessTransport {
   // (own-property-preserving, retained in `_rawResponses` — see
   // constructor doc) and once through the SDK's own `JSONRPCMessageSchema`
   // (routed to `onmessage`, unchanged behavior for the Client/Protocol).
-  _drain() {
-    while (this._buffer) {
-      const index = this._buffer.indexOf('\n');
-      if (index === -1) return;
-      const line = this._buffer.toString('utf8', 0, index).replace(/\r$/, '');
-      this._buffer = this._buffer.subarray(index + 1);
+  _drain(chunk) {
+    // Retain fragments without copying or rescanning the growing partial
+    // frame on every pipe read. Join once, only when a newline arrives.
+    let offset = 0;
+    while (offset < chunk.length) {
+      const newline = chunk.indexOf(10, offset);
+      const end = newline === -1 ? chunk.length : newline;
+      if (end > offset) {
+        (this._buffer ??= []).push(chunk.subarray(offset, end));
+        this._bufferBytes += end - offset;
+      }
+      if (newline === -1) return;
+      const frame = this._buffer?.length === 1
+        ? this._buffer[0] : Buffer.concat(this._buffer ?? [], this._bufferBytes);
+      const line = frame.toString('utf8').replace(/\r$/, '');
+      this._buffer = undefined;
+      this._bufferBytes = 0;
       this._handleLine(line);
-      if (this._buffer?.length === 0) this._buffer = undefined;
+      if (this._closed || this._failure) return;
+      offset = newline + 1;
     }
   }
 
@@ -905,6 +984,7 @@ export class ChildProcessTransport {
       try { signalChild(child, 'SIGKILL'); } catch { /* already gone */ }
     }
     this._buffer = undefined;
+    this._bufferBytes = 0;
   }
 }
 
@@ -1745,6 +1825,24 @@ export async function registerWorkerInvokeToolset(server, options = {}) {
     }
     const { root, snapshot, drivers, invocation } = prefix;
 
+    // #3685 round 2: the worker CLI's AIWG bootstrap must be present in
+    // the worker workdir before dispatch — a context-free worker would run
+    // with no project rules/skills/hooks. Present: no-op. Missing: exactly
+    // one `aiwg use all` pass into the workdir (never elsewhere). A failed
+    // ensure refuses as `blocked` with the typed diagnostic (never a
+    // launch). Default on; `ensureWorkerContext: false` skips (synthetic
+    // tests), a function value replaces the ensure.
+    if (options.ensureWorkerContext !== false) {
+      try {
+        const ensure = typeof options.ensureWorkerContext === 'function'
+          ? options.ensureWorkerContext
+          : ensureWorkerContextForInvocation;
+        await ensure({ invocation, config: snapshot.config });
+      } catch (error) {
+        return markTerminal({ status: 'blocked', termination: 'confirmed', diagnostics: [toWorkerContextDiagnostic(error)] });
+      }
+    }
+
     // =========================================================================
     // #2915 round 8 (D6): ONE decision, immediately after the prefix, from
     // the launcher's own pure eligibility predicate,