@aiwg/cli 2026.10.10 → 2026.10.11

package/dist/src/sessions/repository.js

@@ -2,8 +2,10 @@ import { requireFeaturePackage } from '../features/runtime.js';
 import { CandidateReviewReceiptSchema, DeletionReceiptSchema, IntelligenceCandidateSchema, PromotionDependencyDecisionSchema, PromotionReceiptSchema, SessionContractError, sha256, } from './contracts.js';
 import { coverageFromBatchRun, } from './batch-contracts.js';
 import { redactSessionText, redactSessionValue, sanitizeSessionEvent, sanitizeNativeExtensions } from './policy.js';
+import { extractBatchEventImages, isImageDigest, } from './image-blobs.js';
 import { effectiveSessionLifecycle } from './lifecycle.js';
 import { deriveSessionAnalytics, } from './analytics.js';
+import { HOST_REFERENCE_TABLE_DDL, } from './host-catalog.js';
 const POLICY_PROVIDER_MIGRATION = 'policy-provider-identity:v2';
 const EVENT_ORIGIN_INTENT_MIGRATION = 'event-origin-intent:v1';
 const VISIBLE_SESSION_PREDICATE = `s.lifecycle != 'tombstoned' AND EXISTS (
@@ -114,6 +116,17 @@ export class SessionRepository {
       CREATE TABLE IF NOT EXISTS session_catalog_meta (
         key TEXT PRIMARY KEY, value TEXT NOT NULL
       );
+      -- Content-addressed tool-output image bytes (#3265). One row per
+      -- content hash per catalog: repeat imports of identical images share
+      -- the row (INSERT OR IGNORE). Events reference blobs by digest and
+      -- keep only a bracketed image placeholder (sha256, type, size) in
+      -- searchableText, so image bytes never reach FTS. Pre-#3265 rows with
+      -- inline bytes are left untouched (no destructive migration).
+      CREATE TABLE IF NOT EXISTS session_image_blobs (
+        digest TEXT PRIMARY KEY, media_type TEXT NOT NULL,
+        byte_length INTEGER NOT NULL, source_locator TEXT,
+        source_offset INTEGER, bytes BLOB NOT NULL
+      );
       CREATE TABLE IF NOT EXISTS session_analytics_facts (
         fact_id TEXT PRIMARY KEY, workspace_id TEXT NOT NULL,
         session_id TEXT NOT NULL, event_id TEXT NOT NULL,
@@ -144,6 +157,9 @@ export class SessionRepository {
       -- alignment without reading searchable text or event JSON.
       CREATE INDEX IF NOT EXISTS idx_fts_event_id ON session_event_fts_content(c0);
     `);
+        // Workspace pointers at account-scoped sessions stored in the host
+        // catalog (#3232). References, never copies; legacy copied rows stay.
+        this.db.exec(HOST_REFERENCE_TABLE_DDL);
         const deletionReceiptColumns = this.db.prepare('PRAGMA table_info(deletion_receipts)').all().map((row) => String(row.name));
         if (!deletionReceiptColumns.includes('workspace_id')) {
             this.db.exec('ALTER TABLE deletion_receipts ADD COLUMN workspace_id TEXT');
@@ -479,6 +495,18 @@ export class SessionRepository {
         };
     }
     applyImport(batch, checkpoint, publish = true) {
+        // Lift inline image payloads out of event text before redaction (#3265):
+        // base64 data URLs in text survive redaction and would otherwise be
+        // stored inline. Provider image blocks in extensions keep their existing
+        // redaction to markers; their bytes are not retained.
+        // Idempotent -- placeholder text from an earlier pass matches no image
+        // pattern, so importer-extracted batches and direct writers converge.
+        // Bytes are parked beside the batch: the redaction pass below walks
+        // every value and would flatten Uint8Array into plain objects.
+        const extracted = extractBatchEventImages(batch);
+        const imageBlobs = extracted.imageBlobs;
+        batch = { ...batch, events: extracted.events };
+        delete batch.imageBlobs;
         // Guard callers that submit normalized batches directly as well as adapters.
         batch = redactSessionValue({
             ...batch,
@@ -525,6 +553,17 @@ export class SessionRepository {
                 const merged = mergeSessionAggregate(prior, session);
                 this.db.prepare(`UPDATE sessions SET source_digest=?, lifecycle=?, data=? WHERE session_id=?`).run(merged.sourceDigest, merged.lifecycle, JSON.stringify(merged), merged.sessionId);
             }
+            // Persist image bytes once per content hash per catalog (#3265).
+            // INSERT OR IGNORE keeps the first-seen row when identical images
+            // arrive in later batches or replayed records.
+            const insertImageBlob = this.db.prepare(`INSERT OR IGNORE INTO session_image_blobs
+         (digest, media_type, byte_length, source_locator, source_offset, bytes)
+         VALUES (?, ?, ?, ?, ?, ?)`);
+            for (const image of imageBlobs) {
+                if (!isImageDigest(image.digest))
+                    continue;
+                insertImageBlob.run(image.digest, image.mediaType, image.byteLength, image.locatorClass ?? null, image.offset ?? null, Buffer.from(image.bytes));
+            }
             const insertEvent = this.db.prepare(`INSERT OR IGNORE INTO session_events
          (event_id, session_id, source_id, import_run_id, sequence_no, digest, data)
          VALUES (?, ?, ?, ?, ?, ?, ?)`);
@@ -746,6 +785,49 @@ export class SessionRepository {
     listWorkspaceIds() {
         return this.db.prepare('SELECT DISTINCT workspace_id FROM sessions ORDER BY workspace_id').all().map((row) => String(row.workspace_id));
     }
+    /**
+     * Record a workspace pointer at an account-scoped session stored in the
+     * host catalog (#3232). Non-destructive: existing copied rows are left
+     * untouched and remain readable.
+     */
+    recordHostSessionReference(reference) {
+        this.db.prepare(`INSERT INTO session_host_refs
+         (provider, native_session_id, session_id, source_id, host_catalog)
+       VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT(provider, native_session_id) DO UPDATE SET
+         session_id=excluded.session_id, source_id=excluded.source_id,
+         host_catalog=excluded.host_catalog`).run(reference.provider, reference.nativeSessionId, reference.sessionId, reference.sourceId, reference.hostCatalog);
+    }
+    listHostSessionReferences() {
+        return this.db.prepare(`SELECT provider, native_session_id, session_id, source_id, host_catalog
+       FROM session_host_refs ORDER BY provider, native_session_id`).all().map((row) => ({
+            provider: String(row.provider),
+            nativeSessionId: String(row.native_session_id),
+            sessionId: String(row.session_id),
+            sourceId: String(row.source_id),
+            hostCatalog: String(row.host_catalog),
+        }));
+    }
+    /**
+     * Visible sessions reduced to aggregate identities (plus the internal ids
+     * reference recording needs). Aggregate search/analytics over several
+     * catalogs dedupe on provider + native session so legacy copied rows
+     * count once (#3232).
+     */
+    listSessionIdentities(workspaceId) {
+        const where = workspaceId
+            ? `s.workspace_id=? AND ${VISIBLE_SESSION_PREDICATE}`
+            : VISIBLE_SESSION_PREDICATE;
+        const params = workspaceId ? [workspaceId] : [];
+        return this.db.prepare(`SELECT json_extract(s.data, '$.provider') AS provider, s.native_session_id,
+              s.session_id, s.source_id
+       FROM sessions s WHERE ${where} ORDER BY s.session_id`).all(...params).map((row) => ({
+            provider: String(row.provider),
+            nativeSessionId: String(row.native_session_id),
+            sessionId: String(row.session_id),
+            sourceId: String(row.source_id),
+        }));
+    }
     saveBatchImportRun(run) {
         run = redactSessionValue(run).value;
         const save = this.db.transaction(() => {
@@ -889,6 +971,62 @@ export class SessionRepository {
        ORDER BY e.sequence_no, e.event_id`).all(...(workspaceId ? [sessionId, workspaceId] : [sessionId]))
             .map((row) => JSON.parse(String(row.data)));
     }
+    /**
+     * Distinct image blobs in this catalog. Identical images share one row
+     * per content hash, so this counts unique images, not references (#3265).
+     */
+    countImageBlobs() {
+        return Number(this.db.prepare('SELECT COUNT(*) AS count FROM session_image_blobs').get()?.count ?? 0);
+    }
+    /**
+     * Fetch one image blob by content digest. Returns null when the blob is
+     * unknown or the digest is malformed -- callers report that as an
+     * "unavailable" reference rather than failing the whole read (#3265).
+     * Pre-#3265 rows carry inline bytes instead of references and never reach
+     * this lookup; they load verbatim through `listEvents`.
+     */
+    getImageBlob(digest) {
+        if (!isImageDigest(digest))
+            return null;
+        const row = this.db.prepare(`SELECT digest, media_type, byte_length, source_locator, source_offset, bytes
+       FROM session_image_blobs WHERE digest=?`).get(digest);
+        if (!row)
+            return null;
+        return {
+            digest: String(row.digest),
+            mediaType: String(row.media_type),
+            byteLength: Number(row.byte_length),
+            sourceLocator: row.source_locator === null ? null : String(row.source_locator),
+            sourceOffset: row.source_offset === null ? null : Number(row.source_offset),
+            bytes: Uint8Array.from(row.bytes),
+        };
+    }
+    /**
+     * Resolve an event's image references against the blob store. Entries
+     * whose bytes are present resolve `available`; entries whose blob is
+     * missing (pruned catalog, legacy reference) resolve `unavailable` with
+     * the reference metadata intact so callers can report it (#3265). Events
+     * without references -- including pre-#3265 inline rows -- resolve to [].
+     */
+    resolveEventImages(event) {
+        return (event.imageRefs ?? []).map((ref) => {
+            const stored = this.getImageBlob(ref.digest);
+            if (!stored)
+                return { ...ref, status: 'unavailable' };
+            return {
+                digest: ref.digest,
+                mediaType: stored.mediaType,
+                byteLength: stored.byteLength,
+                ...(ref.locatorClass !== undefined
+                    ? { locatorClass: ref.locatorClass }
+                    : stored.sourceLocator !== null ? { locatorClass: stored.sourceLocator } : {}),
+                ...(ref.offset !== undefined
+                    ? { offset: ref.offset }
+                    : stored.sourceOffset !== null ? { offset: stored.sourceOffset } : {}),
+                status: 'available',
+            };
+        });
+    }
     listTimelineInputs(workspaceId) {
         return this.db.prepare(`SELECT s.data AS session_data, e.data AS event_data
        FROM session_events e
@@ -1168,28 +1306,7 @@ export class SessionRepository {
     }
     analyticsSummary(options) {
         const facts = this.listAnalyticsFacts({ ...options, limit: options.limit ?? 5_000 });
-        const byCategory = countBy(facts, (fact) => fact.category);
-        const byStatus = countBy(facts, (fact) => fact.status);
-        const byProvider = countBy(facts, (fact) => fact.provider);
-        const byTool = countBy(facts.filter((fact) => fact.toolName), (fact) => fact.toolName);
-        return {
-            analyticsVersion: '1.0.0',
-            workspaceId: options.workspaceId,
-            totals: {
-                facts: facts.length,
-                sessions: new Set(facts.map((fact) => fact.sessionId)).size,
-                toolCalls: facts.filter((fact) => fact.category === 'tool-call').length,
-                toolFailures: facts.filter((fact) => fact.category === 'tool-result' && fact.status === 'failed').length,
-                escalations: facts.filter((fact) => fact.category === 'escalation').length,
-                hitlDecisions: facts.filter((fact) => fact.category === 'hitl').length,
-                indicators: facts.filter((fact) => fact.category === 'indicator').length,
-                retryGroups: new Set(facts.map((fact) => fact.retryGroupId).filter(Boolean)).size,
-            },
-            byCategory,
-            byStatus,
-            byProvider,
-            byTool,
-        };
+        return summarizeSessionAnalyticsFacts(facts, options.workspaceId);
     }
     getAnalyticsEvidence(id, workspaceId) {
         const row = this.db.prepare(`SELECT f.data AS fact_data, e.data AS event_data
@@ -1852,6 +1969,31 @@ function canonicalDevinLocator(value) {
         ? `devin-desktop-${value.slice('windsurf-'.length)}`
         : value;
 }
+/**
+ * Summarize analytics facts without touching a catalog, so cross-catalog
+ * merges (workspace facts plus referenced host facts, #3232) report the
+ * same shape as a single-catalog summary.
+ */
+export function summarizeSessionAnalyticsFacts(facts, workspaceId) {
+    return {
+        analyticsVersion: '1.0.0',
+        workspaceId,
+        totals: {
+            facts: facts.length,
+            sessions: new Set(facts.map((fact) => fact.sessionId)).size,
+            toolCalls: facts.filter((fact) => fact.category === 'tool-call').length,
+            toolFailures: facts.filter((fact) => fact.category === 'tool-result' && fact.status === 'failed').length,
+            escalations: facts.filter((fact) => fact.category === 'escalation').length,
+            hitlDecisions: facts.filter((fact) => fact.category === 'hitl').length,
+            indicators: facts.filter((fact) => fact.category === 'indicator').length,
+            retryGroups: new Set(facts.map((fact) => fact.retryGroupId).filter(Boolean)).size,
+        },
+        byCategory: countBy(facts, (fact) => fact.category),
+        byStatus: countBy(facts, (fact) => fact.status),
+        byProvider: countBy(facts, (fact) => fact.provider),
+        byTool: countBy(facts.filter((fact) => fact.toolName), (fact) => fact.toolName),
+    };
+}
 function countBy(items, key) {
     const counts = {};
     for (const item of items) {

package/dist/src/sessions/workspace-discovery.js

@@ -269,10 +269,13 @@ export async function discoverWorkspaceHistories(options) {
                 // old entries, so a content-digest sourceId (the default above)
                 // would churn every re-discovery and break checkpoint continuity.
                 // Key it on the conversation id instead, same rationale as the OMP
-                // override above.
+                // override above. Unlike OMP, the key carries no workspaceId: Grok
+                // Bot conversations are account-scoped (#3232), so the same replica
+                // must resolve to one host-catalog source no matter which workspace
+                // authorizes it; workspace catalogs keep a reference instead of a copy.
                 const conversationId = grokbotConversationIdFromLocator(locator);
                 if (conversationId) {
-                    source.sourceId = sha256(['grokbot-native-source-v1', workspaceId, conversationId].join('\0'));
+                    source.sourceId = sha256(['grokbot-native-source-v1', conversationId].join('\0'));
                 }
             }
             providerSources.push(source);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cli",
-  "version": "2026.10.10",
+  "version": "2026.10.11",
   "description": "Lightweight AIWG CLI for signed, versioned web-backed resources.",
   "type": "module",
   "license": "MIT",
@@ -54,6 +54,12 @@
     "tools/ralph-external/lib/worker-launch-cli.mjs",
     "tools/ralph-external/lib/worker-isolation.mjs",
     "tools/ralph-external/lib/worker-native-sandbox.mjs",
+    "tools/ralph-external/lib/worker-isolation-status.mjs",
+    "tools/ralph-external/lib/worker-retry-evidence.mjs",
+    "tools/ralph-external/lib/worker-termination.mjs",
+    "tools/ralph-external/lib/worker-invocation-processes.mjs",
+    "tools/ralph-external/lib/worker-invocation-ancestry.mjs",
+    "tools/ralph-external/lib/worker-context.mjs",
     "tools/ralph-external/lib/systemd-client.mjs",
     "tools/ralph-external/lib/consecutive-failure-circuit-breaker.mjs",
     "tools/ralph-external/lib/launcher-recovery-evidence.mjs",

package/tools/ralph-external/lib/muse-adapter.mjs

@@ -31,6 +31,13 @@
  *   - `--approval-mode <mode>` — common to both; "`muse exec` accepts both
  *     approval flags" (configuration). Opt-in only: the adapter sets NO
  *     approval posture by default (#230 out of scope: `--yolo` defaults).
+ *   - `--trust-workspace` — loads project rules, skills and hooks for the
+ *     workspace (#3685: untrusted Muse reports `rules.context_load`
+ *     `project_sources=0` with user skills only and empty hook admission;
+ *     trusted reports `project_sources=1` with project skills and hooks).
+ *     Tier 0 workspaces are conductor-prepared worker trees the conductor
+ *     owns, so the direct profile binds this flag by default through the
+ *     host-controlled trust mapping; the brief never supplies it.
  *   - `muse export --session <uuid> --out <path>` — offline,
  *     byte-deterministic transcript projection; `--last` and `--redacted`
  *     skip the picker / redact payload strings (cookbook:
@@ -173,6 +180,9 @@ export class MuseAdapter extends ProviderAdapter {
     if ((permissions.approval ?? 'never') !== 'never') throw new Error('Muse direct worker approval requires never');
     // Trust is a host-owned, qualification-bound control, like the schema.
     // Brief contents and CLI defaults cannot opt into workspace instructions.
+    // Tier 0 binds ["--trust-workspace"] because the workspace is always a
+    // conductor-prepared worker tree (#3685); untrusted trees stay refused
+    // at dispatch by the operator native-argv gate.
     let trust;
     try { trust = JSON.parse(profile.controls.trust.mapping); } catch { /* fail closed below */ }
     if (!Array.isArray(trust) || !(trust.length === 0 || trust.length === 1 && trust[0] === '--trust-workspace')) {

package/tools/ralph-external/lib/worker-context.mjs

@@ -0,0 +1,237 @@
+/**
+ * Worker AIWG context loading and launch-time ensure, tools side (#3685).
+ *
+ * The provider-set UNION lives in `src/config/worker-context.ts` and the
+ * config loads through the existing `readAiwgConfig` loader (never ad-hoc
+ * JSON). Both cross the tools/src boundary through `importImpl`, so this
+ * module stays runnable from an installed package (`dist/src`) and a
+ * checkout (`src/`); every such seam is injectable for synthetic tests.
+ * `src/` must never import `tools/`, so the src module is always the
+ * callee, never the caller.
+ *
+ * Also home to the single-pass deploy, section verifier, and
+ * skip-worktree helpers extracted from `worktree-preparation.mjs` (which
+ * re-exports them) so that file stays agent-friendly.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { importImpl } from '../../_resolve-impl.mjs';
+
+/** Load the project config through the existing loader. */
+async function defaultReadConfig(repoRoot) {
+  const { readAiwgConfig } = await importImpl(import.meta.url, 'config/aiwg-config.js');
+  return readAiwgConfig(repoRoot);
+}
+
+/** Resolve the provider union through the src-side pure function. */
+async function defaultResolveFromConfig(config) {
+  const { resolveWorkerContextProvidersFromConfig } = await importImpl(import.meta.url, 'config/worker-context.js');
+  return resolveWorkerContextProvidersFromConfig(config);
+}
+
+/** Map one orchestration CLI id through the src-side registry mapping. */
+async function defaultMapCli(cli, parallelism) {
+  const { mapCliToProviderId } = await importImpl(import.meta.url, 'config/worker-context.js');
+  return mapCliToProviderId(cli, parallelism);
+}
+
+/**
+ * Resolve the worker-context provider set (#3685 round 2): the union of
+ * `.aiwg/aiwg.config` `providers` and every CLI configured for
+ * orchestration (`parallelism.clis` keys/adapters and the `cli` of every
+ * `parallelism.groups.*.members[]`), mapped through the provider
+ * registry. An explicit list wins and is returned verbatim.
+ *
+ * @returns {Promise<{providers: string[], skipped: string[]}>}
+ */
+export async function resolveWorkerContextProviders({ repoRoot, providers = null, readConfig = null, resolveFromConfig = null } = {}) {
+  if (providers !== null && providers !== undefined) {
+    if (!Array.isArray(providers) || providers.length === 0
+      || providers.some(p => typeof p !== 'string' || p.length === 0 || p.includes('\0') || p.includes(','))) {
+      throw new Error('worker context providers must be a non-empty array of provider ids');
+    }
+    return { providers: [...new Set(providers)], skipped: [] };
+  }
+  if (typeof repoRoot !== 'string' || !repoRoot) {
+    throw new Error('worker context providers need a repoRoot or an explicit provider list');
+  }
+  const config = await (readConfig ?? defaultReadConfig)(repoRoot);
+  if (!config) {
+    throw new Error(`worker context deployment needs configured providers: cannot read ${path.join(repoRoot, '.aiwg', 'aiwg.config')} (missing or invalid); configure providers and orchestration CLIs, or pass an explicit provider list`);
+  }
+  return (resolveFromConfig ?? defaultResolveFromConfig)(config);
+}
+
+/**
+ * Ensure a worker workdir carries its CLI's AIWG bootstrap before launch.
+ * Resolves the worker CLI to its provider (from the project config, so
+ * orchestration CLIs map through the registry), checks presence, and
+ * deploys through the same one-pass helper when missing. The deploy
+ * target is always exactly `workdir` — never anywhere else.
+ *
+ * Injectable for synthetic tests: `ensureFn` stubs the whole ensure,
+ * otherwise `mapCli`, `readConfig`, `resolveFromConfig`, `deployFn`,
+ * `statusFn`, and `skipWorktreeFn` stub each seam.
+ *
+ * @returns {Promise<{ensured: boolean, provider: string, providers: string[], skippedBridges: string[], skipped: string[]}>}
+ */
+export async function ensureWorkerContextForLaunch({
+  workdir,
+  cli,
+  config = null,
+  repoRoot = null,
+  providers = null,
+  readConfig = null,
+  resolveFromConfig = null,
+  mapCli = null,
+  ensureFn = null,
+  statusFn = null,
+  deployFn = null,
+  skipWorktreeFn = null,
+  aiwgBin = process.env.AIWG_BIN ?? 'aiwg',
+} = {}) {
+  if (typeof workdir !== 'string' || !workdir) throw new Error('worker context ensure needs a workdir');
+  if (typeof cli !== 'string' || !cli) throw new Error('worker context ensure needs the worker CLI id');
+  let resolved = Array.isArray(providers) && providers.length > 0 ? { providers: [...new Set(providers)], skipped: [] } : null;
+  let loaded = config ?? null;
+  if (!resolved) {
+    if (!loaded && repoRoot) loaded = await (readConfig ?? defaultReadConfig)(repoRoot);
+    if (loaded) {
+      resolved = await (resolveFromConfig ?? defaultResolveFromConfig)(loaded);
+    }
+  }
+  const map = mapCli ?? defaultMapCli;
+  const mapped = await map(cli, loaded?.parallelism ?? null);
+  if (!('provider' in mapped) || !mapped.provider) {
+    // Typed-shaped refusal without importing the src error class (which
+    // would couple this sync-throwing path to the compiled `dist`
+    // layout): callers discriminate on `code`, never `instanceof`.
+    throw Object.assign(
+      new Error(`cannot ensure worker context: CLI '${cli}' maps to no AIWG provider (${mapped.skipped ?? 'unmapped'})`),
+      { code: 'OG_WORKER_CONTEXT_UNAVAILABLE',
+        remedy: `configure parallelism.clis.${cli} with a providers:<id> adapter, or use a CLI whose adapter maps to a known provider`,
+        workdir },
+    );
+  }
+  const provider = mapped.provider;
+  const deployProviders = resolved ? [...new Set([...resolved.providers, provider])] : [provider];
+  const ensure = ensureFn ?? (async (opts) => {
+    const { ensureWorkerContextBootstrap } = await importImpl(import.meta.url, 'config/worker-context.js');
+    return ensureWorkerContextBootstrap(opts);
+  });
+  const outcome = await ensure({
+    workdir, provider, providers: deployProviders, aiwgBin,
+    ...(statusFn ? { statusFn } : {}),
+    ...(deployFn ? { deployFn } : {}),
+    ...(skipWorktreeFn ? { skipWorktreeFn } : {}),
+  });
+  return { ...outcome, provider, skipped: resolved?.skipped ?? [] };
+}
+
+/** Materialize the union set into the worktree config through the src-side sync. */
+async function defaultSyncProviders(worktreePath, providers) {
+  const { syncWorkerContextProviders } = await importImpl(import.meta.url, 'config/worker-context.js');
+  return syncWorkerContextProviders({ workdir: worktreePath, providers });
+}
+
+/** Single-pass argv through the src-side canonical builder (never `--providers`). */
+async function defaultDeployArgv(providers, worktreePath) {
+  const { buildWorkerContextDeployArgs } = await importImpl(import.meta.url, 'config/worker-context.js');
+  return buildWorkerContextDeployArgs({ providers, target: worktreePath });
+}
+
+/**
+ * Default single-pass AIWG context deploy (#3685): sync the union set
+ * into the worktree config, then one `aiwg use all --target <worktree>`
+ * covering every configured provider. Never one deploy per provider:
+ * per-provider invocations rewrite AGENTS.md piecemeal and clobber each
+ * other's rule sections, while a single pass keeps them all. No
+ * `--providers` flag: it never reaches project-scope deploys
+ * (`executeCore` resolves from config), so the configured-provider path
+ * above is the supported mechanism. Injectable via
+ * `prepareWorkerWorktree()`'s `deployContextFn` for synthetic tests;
+ * `syncFn` stubs the config sync as `(worktreePath, providers)` and
+ * `argvFn` stubs the argv builder as `(providers, target)`.
+ *
+ * @returns {Promise<{providers: string[]}>}
+ */
+export async function defaultDeployWorkerContext({ worktreePath, providers, aiwgBin = 'aiwg', spawn = spawnSync, timeoutMs = 300000, syncFn = null, argvFn = null } = {}) {
+  if (typeof worktreePath !== 'string' || !worktreePath || typeof aiwgBin !== 'string' || !aiwgBin) {
+    throw new Error('worker context deploy requires a worktree path and an aiwg binary');
+  }
+  if (!Array.isArray(providers) || providers.length === 0) {
+    throw new Error('worker context deploy requires a non-empty provider list');
+  }
+  const sync = syncFn ?? defaultSyncProviders;
+  const synced = await sync(worktreePath, providers);
+  const syncedProviders = Array.isArray(synced?.providers) && synced.providers.length > 0 ? synced.providers : [...providers];
+  const buildArgv = argvFn ?? defaultDeployArgv;
+  const argv = await buildArgv(syncedProviders, worktreePath);
+  const result = spawn(aiwgBin, argv, { cwd: worktreePath, encoding: 'utf8', timeout: timeoutMs });
+  if (result.error) throw new Error(`aiwg ${argv.join(' ')} failed to run: ${result.error.message}`);
+  if (result.status !== 0) {
+    throw new Error(`aiwg ${argv.join(' ')} exited ${result.status}: ${String(result.stderr ?? '').trim().slice(0, 2000)}`);
+  }
+  return { providers: [...syncedProviders] };
+}
+
+/** 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*-->/;
+
+/**
+ * Verify a prepared worktree actually carries AIWG rule sections (#3685):
+ * the worktree's AGENTS.md must exist and contain AIWG-managed section
+ * markers. Throws before launch otherwise — a worktree without them would
+ * run the worker with no project rules/skills/hooks. Injectable via
+ * `prepareWorkerWorktree()`'s `verifyContextFn` for synthetic tests.
+ *
+ * @returns {{verified: boolean, providers: string[]}}
+ */
+export function verifyWorkerContextSections({ worktreePath, providers = [] } = {}) {
+  const agentsMd = path.join(worktreePath, 'AGENTS.md');
+  let content;
+  try {
+    content = readFileSync(agentsMd, 'utf8');
+  } catch {
+    throw new Error(`worker context verification failed: ${agentsMd} is missing; the worker would run without AIWG rule sections`);
+  }
+  if (!WORKER_CONTEXT_RULE_MARKER.test(content)) {
+    throw new Error(`worker context verification failed: ${agentsMd} has no AIWG rule sections (expected <!-- AIWG:<rule>:start --> markers for ${[...providers].join(',') || 'the configured providers'})`);
+  }
+  return { verified: true, providers: [...providers] };
+}
+
+/**
+ * Tracked files the context deploy modified, so the caller can hide them
+ * from the worker diff. Parses `git status --porcelain=v1` with untracked
+ * files excluded: every remaining entry is a tracked modification (the
+ * fresh worktree starts clean, so each one is deploy-caused).
+ *
+ * @returns {string[]} Repo-relative paths of tracked-modified files.
+ */
+export function listDeployDirtiedBridges({ worktreePath, spawn = spawnSync, timeoutMs = 30000 } = {}) {
+  // Raw spawn output, never a trimmed helper: trim would eat the
+  // significant leading space of the first porcelain line (` M AGENTS.md`
+  // trims to `M AGENTS.md`, shifting slice(3) one byte into the filename).
+  const result = spawn('git', ['status', '--porcelain=v1', '--untracked-files=no'], { cwd: worktreePath, encoding: 'utf8', timeout: timeoutMs });
+  if (result.error) throw new Error(`git status failed to run: ${result.error.message}`);
+  if (result.status !== 0) {
+    throw new Error(`git status exited ${result.status}: ${String(result.stderr ?? '').trim()}`);
+  }
+  const files = [];
+  for (const line of String(result.stdout ?? '').split('\n')) {
+    if (!line.trim()) continue;
+    // `XY PATH` or `XY ORIG -> NEW` for renames; take the new path, which is
+    // what the worker diff would report.
+    const raw = line.slice(3);
+    const arrow = raw.indexOf(' -> ');
+    const rel = arrow >= 0 ? raw.slice(arrow + 4) : raw;
+    // Porcelain quotes paths with special bytes; a deploy that creates such
+    // a name is refused rather than mis-flagged.
+    if (!rel || rel.startsWith('"')) throw new Error(`worker context deploy dirtied an unflaggeable path: ${line}`);
+    files.push(rel);
+  }
+  return files;
+}