@animalabs/connectome-host 0.7.3 → 0.8.0

package/src/modules/identity-module.ts

@@ -33,6 +33,7 @@ import {
   createPublicKey,
   generateKeyPairSync,
   sign as cryptoSign,
+  createHash,
   type KeyObject,
 } from 'node:crypto';
 import type {
@@ -41,6 +42,7 @@ import type {
   ToolCall,
   ToolResult,
   ToolDefinition,
+  WorkspaceModule,
 } from '@animalabs/agent-framework';
 
 export interface IdentityModuleConfig {
@@ -51,10 +53,57 @@ export interface IdentityModuleConfig {
   home: string;
   /** Audience assumed when none is named. */
   defaultAudience?: string;
+  /**
+   * Services reachable through the `request` utility: audience name → API
+   * base URL. The allowlist IS the security boundary — the host only ever
+   * attaches standing access to these bases, so the utility can't be
+   * steered at arbitrary URLs. Merged over built-in defaults for the
+   * animalabs services.
+   */
+  services?: Record<string, string>;
   /** Injectable for tests. */
   fetchImpl?: typeof fetch;
 }
 
+/** Known services when anchored at the animalabs home — a recipe can extend
+ *  or override via `services`. */
+const DEFAULT_SERVICES: Record<string, string> = {
+  orrery: 'https://orrery.animalabs.ai',
+  eidoverse: 'https://eidoverse.animalabs.ai',
+};
+
+/** How long a fetched service directory is trusted before a background-ish
+ *  refresh. Short by design: "a service changed" should reach residents in
+ *  about a minute, and an unknown name forces a refresh immediately anyway. */
+const SERVICES_TTL_MS = 60_000;
+const SERVICES_TIMEOUT_MS = 5_000;
+
+const REQUEST_BODY_MAX = 256 * 1024;
+/** Uploads are bytes the host streams from a workspace file, not text the
+ *  model wrote, so the small JSON-body cap would be the wrong limit: a track
+ *  or a render is legitimately megabytes. Still bounded — one call should not
+ *  be able to push an unbounded file at a service. */
+const UPLOAD_BODY_MAX = 64 * 1024 * 1024;
+
+/** Enough to label the common uploads honestly; anything else is
+ *  application/octet-stream unless the caller says otherwise. */
+const CONTENT_TYPES: Record<string, string> = {
+  mp3: 'audio/mpeg', wav: 'audio/wav', flac: 'audio/flac', ogg: 'audio/ogg',
+  opus: 'audio/opus', m4a: 'audio/mp4', aac: 'audio/aac',
+  png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif',
+  webp: 'image/webp', svg: 'image/svg+xml',
+  mp4: 'video/mp4', webm: 'video/webm', mov: 'video/quicktime',
+  json: 'application/json', txt: 'text/plain', md: 'text/markdown',
+  pdf: 'application/pdf', zip: 'application/zip',
+};
+
+function guessContentType(path: string): string {
+  const ext = path.slice(path.lastIndexOf('.') + 1).toLowerCase();
+  return CONTENT_TYPES[ext] ?? 'application/octet-stream';
+}
+const RESPONSE_INLINE_MAX = 24 * 1024;
+const RESPONSE_BODY_MAX = 64 * 1024 * 1024;
+
 /** Persisted beside the key after a successful registration. */
 interface IdentityRecord {
   sub: string;
@@ -74,12 +123,19 @@ export class IdentityModule implements Module {
   readonly name = 'identity';
   private readonly recordPath: string;
 
+  /** Last good service directory from the home node, and when we got it. */
+  private servicesFromHome: Record<string, string> = {};
+  private servicesFetchedAt = 0;
+  private servicesInflight: Promise<void> | null = null;
+
   constructor(private readonly config: IdentityModuleConfig) {
     this.recordPath = config.keyPath.replace(/\.pem$/, '') + '.json';
   }
 
-  async start(_ctx: ModuleContext): Promise<void> {}
-  async stop(): Promise<void> {}
+  private ctx: ModuleContext | null = null;
+
+  async start(ctx: ModuleContext): Promise<void> { this.ctx = ctx; }
+  async stop(): Promise<void> { this.ctx = null; }
 
   getTools(): ToolDefinition[] {
     return []; // utilities-only, by design — see module header
@@ -95,6 +151,30 @@ export class IdentityModule implements Module {
           'managed by the host from this — you never handle credentials yourself.',
         inputSchema: { type: 'object', properties: {} },
       },
+      {
+        name: 'request',
+        description:
+          'Call a connected service’s API (e.g. "orrery") with your standing access ' +
+          'attached by the host — nothing for you to obtain, renew, or handle; renewal ' +
+          'is automatic. Give the service name and a path; returns {status, body}. ' +
+          'For binary responses, pass saveAs with a workspace path (e.g. files/artifacts/image.png). ' +
+          'To send a file — audio, images, anything large — pass fromFile with a workspace ' +
+          'path instead of body; the host streams the bytes, so the file never has to pass ' +
+          'through what you are writing.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            service: { type: 'string', description: 'Service name, e.g. "orrery". Unknown names list what is available.' },
+            path: { type: 'string', description: 'API path starting with "/", e.g. "/api/ops".' },
+            method: { type: 'string', enum: ['GET', 'POST', 'PUT', 'DELETE'], description: 'Default GET.' },
+            body: { type: 'object', description: 'JSON body for POST/PUT.' },
+            fromFile: { type: 'string', description: 'Workspace path whose raw bytes become the request body, e.g. files/music/track.mp3. Use instead of body for uploads; not combinable with it.' },
+            contentType: { type: 'string', description: 'Content-Type for fromFile uploads. Inferred from the file extension when omitted.' },
+            saveAs: { type: 'string', description: 'Optional workspace path for the raw response bytes, e.g. files/artifacts/image.png. Required to retrieve binary bodies without loss.' },
+          },
+          required: ['service', 'path'],
+        },
+      },
       {
         name: 'accept_invite',
         description:
@@ -120,6 +200,8 @@ export class IdentityModule implements Module {
           return this.status();
         case 'accept_invite':
           return await this.acceptInvite(call.input as { invite?: unknown; name?: unknown });
+        case 'request':
+          return await this.request(call.input as { service?: unknown; path?: unknown; method?: unknown; body?: unknown; saveAs?: unknown });
         default:
           return fail(`Unknown identity utility: ${call.name}`);
       }
@@ -239,6 +321,232 @@ export class IdentityModule implements Module {
     );
   }
 
+  /** Audience → API base, resolved from the home node's `/services` directory
+   *  at runtime. The archipelago's service list belongs to the trust anchor,
+   *  not to a constant compiled into every host: a service added at the home
+   *  node reaches every resident without a restart or a recipe edit.
+   *
+   *  Layering, most specific last: fetched directory → built-in defaults for
+   *  anything the directory omits → recipe `services` (explicit local config
+   *  still wins, for testing and for hosts anchored elsewhere).
+   *
+   *  Never throws: a home node that is down, slow, or rate-limiting leaves the
+   *  last good directory in place (or the built-in defaults on a cold start),
+   *  so losing discovery degrades to today's behaviour rather than to an
+   *  outage. */
+  private async resolveServices(opts: { force?: boolean } = {}): Promise<Record<string, string>> {
+    const now = Date.now();
+    const fresh = this.servicesFetchedAt > 0 && now - this.servicesFetchedAt < SERVICES_TTL_MS;
+    if (!opts.force && fresh) return this.layerServices();
+    // Collapse concurrent refreshes onto one request.
+    if (!this.servicesInflight) {
+      const f = this.config.fetchImpl ?? fetch;
+      this.servicesInflight = (async () => {
+        try {
+          const res = await f(`https://${this.config.home}/services`, {
+            method: 'GET',
+            headers: { accept: 'application/json' },
+            signal: AbortSignal.timeout(SERVICES_TIMEOUT_MS),
+          });
+          if (!res.ok) throw new Error(`status ${res.status}`);
+          const json = (await res.json()) as { services?: Record<string, unknown> };
+          const map: Record<string, string> = {};
+          for (const [name, base] of Object.entries(json.services ?? {})) {
+            if (typeof base === 'string' && /^https:\/\//.test(base)) map[name] = base;
+          }
+          this.servicesFromHome = map;
+          this.servicesFetchedAt = Date.now();
+        } catch (err) {
+          // Keep whatever we had; note it once per failure for the operator.
+          console.error(
+            `[identity] service directory refresh failed (${this.config.home}): ${err instanceof Error ? err.message : String(err)}`,
+          );
+        } finally {
+          this.servicesInflight = null;
+        }
+      })();
+    }
+    await this.servicesInflight;
+    return this.layerServices();
+  }
+
+  private layerServices(): Record<string, string> {
+    return { ...DEFAULT_SERVICES, ...this.servicesFromHome, ...this.config.services };
+  }
+
+  /** The agent-facing HTTP seam for non-MCPL services (Orrery et al.): the
+   *  host resolves the base URL from the directory, fetches fresh access,
+   *  attaches it, and returns only {status, body}. The credential exists
+   *  for the duration of one fetch, outside model context. */
+  private async request(input: {
+    service?: unknown;
+    path?: unknown;
+    method?: unknown;
+    body?: unknown;
+    fromFile?: unknown;
+    contentType?: unknown;
+    saveAs?: unknown;
+  }): Promise<ToolResult> {
+    const service = typeof input.service === 'string' ? input.service : '';
+    let services = await this.resolveServices();
+    let base = services[service];
+    if (!base && service) {
+      // A name we don't know yet is the likeliest moment for the directory to
+      // have moved under us — a service that went live since our last refresh.
+      // Re-ask once before refusing, so a new archipelago service is usable
+      // immediately rather than after a cache expiry.
+      services = await this.resolveServices({ force: true });
+      base = services[service];
+    }
+    if (!base) {
+      return fail(`Unknown service "${service}". Available: ${Object.keys(services).join(', ')}`);
+    }
+    if (typeof input.path !== 'string' || !input.path.startsWith('/')) {
+      return fail('`path` must be a string starting with "/"');
+    }
+    const method = typeof input.method === 'string' ? input.method.toUpperCase() : 'GET';
+    if (!['GET', 'POST', 'PUT', 'DELETE'].includes(method)) return fail(`unsupported method ${method}`);
+    let bodyStr: string | undefined;
+    if (input.body !== undefined && method !== 'GET') {
+      bodyStr = typeof input.body === 'string' ? input.body : JSON.stringify(input.body);
+      if (bodyStr.length > REQUEST_BODY_MAX) return fail(`body too large (${bodyStr.length} > ${REQUEST_BODY_MAX})`);
+    }
+
+    // Uploads: the agent names a workspace file, the host sends its bytes. The
+    // mirror of saveAs — a file too big to write into a turn is exactly the
+    // case that needs this, so the bytes never enter model context, and the
+    // small JSON body cap does not apply to them.
+    let upload: { bytes: Buffer; contentType: string; path: string } | undefined;
+    if (typeof input.fromFile === 'string' && input.fromFile.length > 0) {
+      if (bodyStr !== undefined) return fail('pass either `body` or `fromFile`, not both');
+      if (method === 'GET') return fail('`fromFile` needs a method with a body (POST or PUT)');
+      const workspace = this.ctx?.getModule<WorkspaceModule>('workspace');
+      if (!workspace) return fail('identity request: workspace module is not available for fromFile');
+      // Disk first, store second. An upload is egress: reading it through the
+      // append-only store would retain every byte forever and refuse anything
+      // binary or over the mount's maxFileSize — which is most media. Disk
+      // has neither problem. The store remains the fallback for a file the
+      // resident wrote through the workspace and never materialized.
+      const diskRead = (workspace as WorkspaceModule & {
+        readBinaryFromDisk?: (
+          path: string,
+          opts?: { maxBytes?: number },
+        ) => Promise<{ data: Buffer; absolutePath: string } | { error: string }>;
+      }).readBinaryFromDisk;
+      const fromDisk = diskRead
+        ? await diskRead.call(workspace, input.fromFile, { maxBytes: UPLOAD_BODY_MAX })
+        : { error: 'this host has no disk read path' };
+      let bytes: Buffer;
+      if (!('error' in fromDisk)) {
+        bytes = fromDisk.data;
+      } else {
+        const fromStore = await workspace.readBinary(input.fromFile);
+        if ('error' in fromStore) {
+          return fail(
+            `identity request: could not read ${input.fromFile}: ${fromDisk.error}; ${fromStore.error}`,
+          );
+        }
+        bytes = fromStore.data;
+      }
+      if (bytes.byteLength > UPLOAD_BODY_MAX) {
+        return fail(`file too large (${bytes.byteLength} > ${UPLOAD_BODY_MAX})`);
+      }
+      upload = {
+        bytes,
+        contentType:
+          typeof input.contentType === 'string' && input.contentType
+            ? input.contentType
+            : guessContentType(input.fromFile),
+        path: input.fromFile,
+      };
+    }
+
+    let access: string;
+    try {
+      access = await this.accessFor(service); // service name == audience name
+    } catch (err) {
+      return fail(err instanceof Error ? err.message : String(err));
+    }
+    const f = this.config.fetchImpl ?? fetch;
+    try {
+      const res = await f(`${base}${input.path}`, {
+        method,
+        headers: {
+          authorization: `Bearer ${access}`,
+          ...(bodyStr !== undefined ? { 'content-type': 'application/json' } : {}),
+          ...(upload ? { 'content-type': upload.contentType } : {}),
+        },
+        ...(bodyStr !== undefined ? { body: bodyStr } : {}),
+        // Uint8Array view, not the Buffer itself: Buffer is not a BodyInit.
+        ...(upload ? { body: new Uint8Array(upload.bytes) } : {}),
+      });
+      const bytes = Buffer.from(await res.arrayBuffer());
+      if (bytes.byteLength > RESPONSE_BODY_MAX) {
+        return fail(`response too large (${bytes.byteLength} > ${RESPONSE_BODY_MAX})`);
+      }
+      const declaredType = res.headers.get('content-type')?.split(';', 1)[0]?.trim().toLowerCase() || '';
+      const contentType = declaredType || 'application/octet-stream';
+      const sha256 = createHash('sha256').update(bytes).digest('hex');
+
+      if (typeof input.saveAs === 'string' && input.saveAs.length > 0) {
+        const workspace = this.ctx?.getModule<WorkspaceModule>('workspace');
+        if (!workspace) return fail('identity request: workspace module is not available for saveAs');
+        const written = await workspace.writeBinary(input.saveAs, bytes, contentType);
+        if (!written.success) return fail(`identity request: could not save response: ${written.error ?? 'unknown'}`);
+        return ok({
+          status: res.status,
+          saved: { path: input.saveAs, size: bytes.byteLength, contentType, sha256 },
+        });
+      }
+
+      const text = bytes.toString('utf8');
+      let parsed: unknown;
+      let parsedJson = false;
+      try {
+        parsed = JSON.parse(text);
+        parsedJson = true;
+      } catch {
+        /* not JSON */
+      }
+      const textual = declaredType.startsWith('text/')
+        || declaredType === 'application/json'
+        || declaredType.endsWith('+json')
+        || declaredType === 'application/xml'
+        || declaredType.endsWith('+xml')
+        // Some tiny internal/fake services omit content-type on JSON. A full
+        // successful parse is a safer fallback than treating valid JSON as
+        // opaque bytes; arbitrary binary almost never parses as one JSON value.
+        || (!declaredType && parsedJson);
+      if (!textual) {
+        return ok({
+          status: res.status,
+          body: null,
+          binary: {
+            size: bytes.byteLength, contentType, sha256,
+            note: 'Binary response omitted from text context; repeat the request with saveAs to write it byte-exactly to a workspace mount.',
+          },
+        });
+      }
+
+      let body: unknown = parsedJson ? parsed : text;
+      const raw = typeof body === 'string' ? body : JSON.stringify(body);
+      if (raw.length > RESPONSE_INLINE_MAX) {
+        body = `${raw.slice(0, RESPONSE_INLINE_MAX)}… [truncated ${raw.length - RESPONSE_INLINE_MAX} chars]`;
+      }
+      return ok({
+        status: res.status,
+        body,
+        // A receipt for what left the house, so an upload is verifiable from
+        // the turn that made it without re-reading the file.
+        ...(upload
+          ? { sent: { path: upload.path, size: upload.bytes.byteLength, contentType: upload.contentType } }
+          : {}),
+      });
+    } catch (err) {
+      return fail(`${service} request failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
   private async acceptInvite(input: { invite?: unknown; name?: unknown }): Promise<ToolResult> {
     if (typeof input.invite !== 'string' || typeof input.name !== 'string') {
       return fail('accept_invite needs { invite, name }');

package/src/modules/instructions-module.ts

@@ -0,0 +1,265 @@
+/**
+ * InstructionsModule — injects a shared, living instructions document into
+ * every agent's context on every turn.
+ *
+ * The document is a CLAUDE.md analogue maintained in a workspace mount:
+ * operators (or the agents themselves, on a read-write mount) edit one file,
+ * and the current content reaches the resident agent AND every ephemeral
+ * subagent via the framework's gatherContext hook before each inference.
+ * Nothing is persisted to Chronicle — position 'system' injections are
+ * per-turn overlays, so edits take effect on the next turn and stale copies
+ * never accumulate in history.
+ *
+ * Fail-open by design: a missing mount, missing file, or any read error
+ * yields no injection (never a blocked inference), with a warning logged
+ * once per distinct error rather than every turn.
+ *
+ * Requires the workspace module: the configured path is a mount-prefixed
+ * workspace path ("<mountName>/<relativePath>") resolved through
+ * WorkspaceModule.resolveAbsolutePath, so mount scoping and the
+ * path-traversal guard apply. validateRecipe enforces the pairing.
+ *
+ * Symlink policy: resolveAbsolutePath's traversal guard is lexical, and a
+ * symlink inside the mount pointing outside it would otherwise smuggle
+ * arbitrary host-readable files into the trusted instructions block. Before
+ * reading, both the mount root and the resolved file are realpath'd and the
+ * file must remain inside the root — the same guard WorkspaceModule applies
+ * to its own image reads. (The right long-term home for this is a safe-read
+ * API on WorkspaceModule itself; agent-framework is a separately released
+ * package, so this module enforces the policy locally until one exists.)
+ *
+ * Reads are bounded: at most maxBytes is ever loaded (the file is read
+ * through a handle, not readFile), so an oversized or growing mounted file
+ * cannot balloon memory past the configured cap.
+ */
+
+import { promises as fs } from 'node:fs';
+import { sep } from 'node:path';
+import type {
+  Module,
+  ModuleContext,
+  ProcessEvent,
+  ProcessState,
+  EventResponse,
+  ToolDefinition,
+  ToolCall,
+  ToolResult,
+} from '@animalabs/agent-framework';
+import type { ContextInjection } from '@animalabs/context-manager';
+
+/**
+ * The slice of WorkspaceModule this module depends on. Structural so tests
+ * can substitute a stub resolver; production wiring passes the real
+ * WorkspaceModule (which satisfies this shape).
+ */
+export interface WorkspacePathResolver {
+  resolveAbsolutePath(mountPrefixedPath: string): string | null;
+}
+
+export interface InstructionsModuleConfig {
+  /** Workspace path "<mountName>/<relativePath>". Default "instructions/AGENTS.md". */
+  path?: string;
+  /** Heading line prepended to the injected block. */
+  header?: string;
+  /** Truncate content beyond this many bytes (with an explicit marker). Default 32768. */
+  maxBytes?: number;
+  /** Where the block lands in the compiled context. Default 'system'. */
+  position?: 'system' | 'beforeUser' | 'afterUser';
+}
+
+export const DEFAULT_INSTRUCTIONS_PATH = 'instructions/AGENTS.md';
+export const DEFAULT_INSTRUCTIONS_HEADER =
+  '# Shared operating instructions (live document)';
+export const DEFAULT_INSTRUCTIONS_MAX_BYTES = 32768;
+
+export class InstructionsModule implements Module {
+  readonly name = 'instructions';
+
+  // gatherContext is a stat + (on change) one file read — well under 2s.
+  // A modest explicit budget keeps a wedged filesystem from eating the
+  // registry-wide 15s default before inference proceeds without us.
+  readonly contextTimeoutMs = 2000;
+
+  private readonly path: string;
+  private readonly header: string;
+  private readonly maxBytes: number;
+  private readonly position: 'system' | 'beforeUser' | 'afterUser';
+
+  private workspace: WorkspacePathResolver | null = null;
+
+  /** Cache keyed by (realpath, mtimeMs, size) — reread only when the file
+   *  changes. The realpath in the key covers a symlink retargeted between
+   *  turns to a different in-mount file with identical stat numbers. */
+  private cached: {
+    realFile: string;
+    mtimeMs: number;
+    size: number;
+    injections: ContextInjection[];
+  } | null = null;
+
+  /** Error messages already warned about — fail-open must not spam per turn. */
+  private warned = new Set<string>();
+
+  constructor(config: InstructionsModuleConfig = {}) {
+    this.path = config.path ?? DEFAULT_INSTRUCTIONS_PATH;
+    this.header = config.header ?? DEFAULT_INSTRUCTIONS_HEADER;
+    this.maxBytes = config.maxBytes ?? DEFAULT_INSTRUCTIONS_MAX_BYTES;
+    this.position = config.position ?? 'system';
+  }
+
+  /** Peer injection (same pattern as setFramework/setIdentity elsewhere). */
+  setWorkspace(workspace: WorkspacePathResolver): void {
+    this.workspace = workspace;
+  }
+
+  async start(_ctx: ModuleContext): Promise<void> {}
+
+  async stop(): Promise<void> {
+    this.cached = null;
+    this.warned.clear();
+  }
+
+  getTools(): ToolDefinition[] {
+    // Passive module — no tools, only gatherContext. The file itself is
+    // read/edited through the workspace module's own tools.
+    return [];
+  }
+
+  async handleToolCall(call: ToolCall): Promise<ToolResult> {
+    return {
+      success: false,
+      error: `InstructionsModule has no tool "${call.name}"`,
+      isError: true,
+    };
+  }
+
+  async onProcess(_event: ProcessEvent, _state: ProcessState): Promise<EventResponse> {
+    return {};
+  }
+
+  /**
+   * Same injection for every agent — resident and ephemeral subagents alike
+   * share the one living document (that is the point of the module).
+   */
+  async gatherContext(_agentName: string): Promise<ContextInjection[]> {
+    if (!this.workspace) {
+      this.warnOnce('workspace module not wired — no instructions injected');
+      return [];
+    }
+
+    const absPath = this.workspace.resolveAbsolutePath(this.path);
+    if (!absPath) {
+      this.warnOnce(
+        `cannot resolve "${this.path}" — unknown mount or path escapes it; no instructions injected`,
+      );
+      return [];
+    }
+    // Mount root, via the same resolver (a bare mount name resolves to the
+    // root). Needed for the realpath containment check below.
+    const mountName = this.path.slice(0, this.path.indexOf('/'));
+    const mountRoot = this.workspace.resolveAbsolutePath(mountName);
+    if (!mountRoot) {
+      this.warnOnce(
+        `cannot resolve mount "${mountName}" root; no instructions injected`,
+      );
+      return [];
+    }
+
+    try {
+      // Symlink guard: resolveAbsolutePath's containment is lexical only, so
+      // realpath both ends and require the real file to still live under the
+      // real mount root. Runs before the cache consult — a symlink swapped
+      // since last turn must never serve (or seed) cached content.
+      const realRoot = await fs.realpath(mountRoot);
+      const realFile = await fs.realpath(absPath);
+      if (realFile !== realRoot && !realFile.startsWith(realRoot + sep)) {
+        this.cached = null;
+        this.warnOnce(
+          `"${this.path}" resolves outside its mount after following symlinks; no instructions injected`,
+        );
+        return [];
+      }
+
+      // Handle-based read: stat and read against one open descriptor (no
+      // stat-then-read race), loading at most maxBytes regardless of file
+      // size — readFile would buffer the whole file first.
+      const handle = await fs.open(realFile, 'r');
+      try {
+        const stat = await handle.stat();
+        if (
+          this.cached &&
+          this.cached.realFile === realFile &&
+          this.cached.mtimeMs === stat.mtimeMs &&
+          this.cached.size === stat.size
+        ) {
+          return this.cached.injections;
+        }
+
+        const readLen = Math.min(stat.size, this.maxBytes);
+        const buf = Buffer.alloc(readLen);
+        let filled = 0;
+        while (filled < readLen) {
+          const { bytesRead } = await handle.read(buf, filled, readLen - filled, filled);
+          if (bytesRead === 0) break; // file shrank mid-read; keep what we have
+          filled += bytesRead;
+        }
+
+        let content: string;
+        if (stat.size > this.maxBytes) {
+          // Back the cut up to a UTF-8 sequence boundary so a multibyte
+          // character split at the cap never decodes to U+FFFD right before
+          // the marker. The bytes past the cap were never read, so detect a
+          // straddle from the kept tail alone: find the last lead byte and
+          // drop the sequence iff it declares more bytes than were kept.
+          let cut = filled;
+          let lead = filled - 1;
+          let trailing = 0;
+          while (lead >= 0 && (buf[lead]! & 0xc0) === 0x80) {
+            lead--;
+            trailing++;
+          }
+          if (lead >= 0) {
+            const b = buf[lead]!;
+            const expected =
+              (b & 0x80) === 0 ? 1
+              : (b & 0xe0) === 0xc0 ? 2
+              : (b & 0xf0) === 0xe0 ? 3
+              : (b & 0xf8) === 0xf0 ? 4
+              : 1; // invalid lead — leave it; decoding was lossy anyway
+            if (expected > trailing + 1) cut = lead;
+          }
+          content =
+            buf.subarray(0, cut).toString('utf-8') +
+            `\n\n[truncated: first ${cut} of ${stat.size} bytes]`;
+        } else {
+          content = buf.subarray(0, filled).toString('utf-8');
+        }
+
+        const injections: ContextInjection[] = [
+          {
+            namespace: 'instructions',
+            position: this.position,
+            content: [{ type: 'text', text: `${this.header}\n\n${content}` }],
+          },
+        ];
+        this.cached = { realFile, mtimeMs: stat.mtimeMs, size: stat.size, injections };
+        // Recovered — let a future recurrence of a previous error warn again.
+        this.warned.clear();
+        return injections;
+      } finally {
+        await handle.close();
+      }
+    } catch (error) {
+      // Fail open: missing file or any read error never blocks inference.
+      this.cached = null;
+      this.warnOnce(error instanceof Error ? error.message : String(error));
+      return [];
+    }
+  }
+
+  private warnOnce(message: string): void {
+    if (this.warned.has(message)) return;
+    this.warned.add(message);
+    console.error(`InstructionsModule: ${message}`);
+  }
+}