@animalabs/agent-framework 0.22.0 → 0.22.1

package/src/index.ts

@@ -92,7 +92,7 @@ export type { McplServerConfig } from './mcpl/index.js';
 // health probes, protocol harnesses — can dial an MCPL server exactly the
 // way the framework host does, over stdio or WebSocket)
 export { McplServerConnection } from './mcpl/index.js';
-export type { McplHostCapabilities } from './mcpl/index.js';
+export type { McplHostCapabilities, McplConnectionCloseInfo } from './mcpl/index.js';
 
 // MCPL tool lifecycle (RFC-007) and tool classes (RFC-008): the types a host
 // needs to write McplServerConfig.toolLifecycle policy and class tables, and
@@ -143,7 +143,12 @@ export type {
 } from './recovery/discord-awareness-outbox.js';
 // Live operator surgery (rollback / suppress) and its durable action log
 export { OperatorLog, OperatorActionError, defaultOperatorLogPath } from './operator-log.js';
-export type { OperatorLogEntry, OperatorLogInput, OperatorRequester } from './operator-log.js';
+export type {
+  OperatorLogEntry,
+  OperatorLogInput,
+  OperatorRequester,
+  SurgeryMarkerReceipt,
+} from './operator-log.js';
 export { createOfflineRecoveryBranch } from './recovery/offline-branch.js';
 export type {
   OfflineRecoveryBranchOptions,

package/src/mcpl/index.ts

@@ -107,6 +107,8 @@ export {
 
 // Server connection and registry
 export { McplServerConnection } from './server-connection.js';
+export type { McplConnectionCloseInfo } from './server-connection.js';
+export type { TransportCloseInfo } from './transport.js';
 export { McplServerRegistry, type McplCapabilityQuery } from './server-registry.js';
 
 // Feature set management (permission layer)

package/src/mcpl/reference-fetcher.ts

@@ -29,7 +29,7 @@
  */
 import { createHash } from 'node:crypto';
 import type { ReferenceRecord } from './references.js';
-import { isReferenceExpired } from './references.js';
+import { EXPIRY_REASON, isReferenceExpired, referenceExpiry, REFERENCE_LIMITS, sanitizeLabel } from './references.js';
 
 /** Per-fetch hard ceiling on actual bytes (overridable per server / call). */
 export const DEFAULT_FETCH_MAX_BYTES = 256 * 1024 * 1024;
@@ -79,13 +79,14 @@ export function sniffMime(data: Buffer): string | null {
   return null;
 }
 
-const EXT_BY_MIME: Record<string, string> = {
+/** A Map, so a server's type such as `constructor` finds no inherited key. */
+const EXT_BY_MIME = new Map<string, string>(Object.entries({
   'audio/wav': 'wav', 'audio/x-wav': 'wav', 'audio/mpeg': 'mp3', 'audio/mp4': 'm4a',
   'audio/flac': 'flac', 'audio/midi': 'mid', 'audio/ogg': 'ogg',
   'image/png': 'png', 'image/jpeg': 'jpg', 'image/gif': 'gif', 'image/webp': 'webp',
   'video/mp4': 'mp4', 'application/json': 'json', 'text/plain': 'txt',
   'application/pdf': 'pdf', 'application/zip': 'zip',
-};
+}));
 
 /** ws→http / wss→https with default ports elided, for origin comparison. */
 export function normalizedOrigin(url: string): string | null {
@@ -111,9 +112,11 @@ export class ReferenceFetcher {
     private readonly saveFile: (fileName: string, data: Buffer, mimeType: string) => Promise<string | null>,
   ) {}
 
-  /** Would the eager (autofetch) default fetch this record? */
+  /** Would the eager (autofetch) default fetch this record? Not one the
+   *  fetcher refuses as expired, which would only take an eager slot. */
   isEagerEligible(record: ReferenceRecord): boolean {
     if (record.fetchedPath) return false;
+    if (isReferenceExpired(record.testimony)) return false;
     if (record.serverId === undefined) return false;
     const binding = this.resolveServer(record.serverId);
     if (!binding) return false;
@@ -161,7 +164,8 @@ export class ReferenceFetcher {
 
     const refusal = this.originCheck(record, binding);
     if (refusal) return { ok: false, error: refusal };
-    if (isReferenceExpired(t)) return { ok: false, error: 'reference expired (or unparseable expiry — fail closed)' };
+    const expiry = referenceExpiry(t);
+    if (expiry) return { ok: false, error: `reference ${EXPIRY_REASON[expiry]}` };
 
     const ceiling = opts?.maxBytes ?? DEFAULT_FETCH_MAX_BYTES;
     // Vector 4: a claim already over the ceiling refuses without dialing.
@@ -215,9 +219,15 @@ export class ReferenceFetcher {
         digestVerified = true;
       }
 
-      const headerMime = resp.headers.get('content-type')?.split(';')[0].trim() || null;
-      const observedMime = sniffMime(data) ?? headerMime ?? t.mimeType ?? 'application/octet-stream';
-      const ext = EXT_BY_MIME[observedMime] ?? EXT_BY_MIME[headerMime ?? ''] ?? EXT_BY_MIME[t.mimeType ?? ''] ?? 'bin';
+      // The response's header and the server's claimed type are both the
+      // server's words, and either can become fetch_reference's mime_type,
+      // the saved type and the record's verified type, so each is shown as a
+      // label is. One left empty once sanitized counts as absent.
+      const header = resp.headers.get('content-type');
+      const headerMime = header !== null ? sanitizeLabel(header.split(';')[0], REFERENCE_LIMITS.mimeType) || null : null;
+      const claimedMime = t.mimeType !== undefined ? sanitizeLabel(t.mimeType, REFERENCE_LIMITS.mimeType) || undefined : undefined;
+      const observedMime = sniffMime(data) ?? headerMime ?? claimedMime ?? 'application/octet-stream';
+      const ext = EXT_BY_MIME.get(observedMime) ?? EXT_BY_MIME.get(headerMime ?? '') ?? EXT_BY_MIME.get(claimedMime ?? '') ?? 'bin';
       // §7.3: host-generated storage name; the server's `name` is display-only.
       const path = await this.saveFile(`${record.refId}.${ext}`, data, observedMime);
       if (path === null) return { ok: false, error: 'no writable workspace mount to store the payload' };

package/src/mcpl/references.ts

@@ -13,7 +13,8 @@
  *  - `disposition:"never"` withholds payload AND uri from model context
  *    unconditionally — enforced in code here, not by caller discipline (§5);
  *  - stub size is independent of every server-supplied field length (§5);
- *  - unparseable `expiresAt` fails closed (§7.4);
+ *  - unparseable `expiresAt` fails closed (§7.4), and so does one rejected
+ *    as a field: it's absent as testimony, never read as immortal;
  *  - unknown block types never propagate `undefined` (the pre-existing
  *    convertBlock switches had no default — a latent corruption this module
  *    retires).
@@ -141,16 +142,42 @@ export function isInlineContradiction(block: unknown): boolean {
 export const INLINE_WITHHELD_TEXT =
   '[inline content withheld: nonconformant bulk disposition on inline data]';
 
-export function isReferenceExpired(t: Pick<ReferenceTestimony, 'expiresAt'>, nowMs = Date.now()): boolean {
-  if (t.expiresAt === undefined) return false;
+/**
+ * Why a reference counts as expired, or null when it doesn't: its expiresAt
+ * has passed, doesn't parse, or was rejected as a field (§7.4, §8). A
+ * rejected expiry (past its schema maximum, or not a string, null included)
+ * is absent as testimony under the one invalid-field rule, but reading that
+ * absence as "never expires" would let field invalidity widen exposure:
+ * like an unparseable one, it fails closed. A reference that claims no
+ * expiry has none.
+ */
+export function referenceExpiry(
+  t: Pick<ReferenceTestimony, 'expiresAt' | 'rejectedFields'>, nowMs = Date.now(),
+): 'rejected' | 'unparseable' | 'passed' | null {
+  if (t.rejectedFields.includes('expiresAt')) return 'rejected';
+  if (t.expiresAt === undefined) return null;
   const exp = Date.parse(t.expiresAt);
-  return Number.isNaN(exp) ? true : exp <= nowMs;
+  if (Number.isNaN(exp)) return 'unparseable';
+  return exp <= nowMs ? 'passed' : null;
+}
+
+export function isReferenceExpired(t: Pick<ReferenceTestimony, 'expiresAt' | 'rejectedFields'>, nowMs = Date.now()): boolean {
+  return referenceExpiry(t, nowMs) !== null;
 }
 
-/** Strip C0/C1 controls plus bidi marks/overrides/isolates; bound length.
+/** Each expiry case as the stub and the fetcher's refusal both say it. */
+export const EXPIRY_REASON = {
+  passed: 'expired: its expiresAt has passed',
+  unparseable: 'treated as expired: its expiresAt does not parse (fail closed)',
+  rejected: `treated as expired: its expiresAt was rejected as a field, over ${REFERENCE_LIMITS.expiresAt} characters or not a string (fail closed)`,
+} as const;
+
+/** Strip control characters (C0, DEL, C1) and every bidi control (marks,
+ *  embeddings, overrides, isolates, and the Arabic letter mark), trim the
+ *  whitespace (a BOM included) left at either end, and bound the length.
  *  Labels are labels — storage naming is host-generated elsewhere (§7.3). */
 export function sanitizeLabel(s: string, maxChars: number): string {
-  const cleaned = s.replace(/[\u0000-\u001F\u007F-\u009F\u200E\u200F\u202A-\u202E\u2066-\u2069]/g, '');
+  const cleaned = s.replace(/[\p{Cc}\p{Bidi_Control}]/gu, '').trim();
   if (cleaned.length <= maxChars) return cleaned;
   let cut = cleaned.slice(0, Math.max(0, maxChars - 1));
   // never split a surrogate pair at the truncation boundary
@@ -187,9 +214,10 @@ const MAX_RECORDS = 2000;
 /**
  * Host-private store of received references. Raw URIs live here and in stubs
  * never (under `never`) or by policy only (`ref`/absent). Ids are stable and
- * never reused within the process (vector 20); eviction is FIFO past
- * MAX_RECORDS and a stale lookup returns undefined — a defined miss, never a
- * different record.
+ * never reused within the process (vector 20). Past MAX_RECORDS the record
+ * registered least recently is evicted (registering a uri the registry holds
+ * makes its record the newest), and a stale lookup returns undefined — a
+ * defined miss, never a different record.
  *
  * Process-wide singleton by design: ids are host-local *names*, not
  * capabilities, and the record itself carries serverId for any future
@@ -222,6 +250,9 @@ export class ReferenceRegistry {
         // describes verified bytes on disk and keeps the testimony they were
         // verified against.
         if (!existing.fetchedPath) existing.testimony = testimony;
+        // Newest again, so a uri just mentioned is the last to be evicted.
+        this.records.delete(existingId);
+        this.records.set(existingId, existing);
         return existing;
       }
     }
@@ -257,6 +288,12 @@ export const referenceRegistry = new ReferenceRegistry();
 // Stub building (§5)
 // ============================================================================
 
+/** A reference's type as its stub shows one, or '' when nothing is left of
+ *  it once sanitized (the stub then leaves it out). */
+export function referenceTypeLabel(mimeType: string | undefined): string {
+  return mimeType ? sanitizeLabel(mimeType, STUB_FIELD_CHARS) : '';
+}
+
 /**
  * Build the model-visible stub for a reference. Output length is bounded by
  * host constants and independent of every server-supplied field length.
@@ -267,18 +304,25 @@ export const referenceRegistry = new ReferenceRegistry();
 export function buildReferenceStub(t: ReferenceTestimony, provenance?: string, serverId?: string): string {
   const record = referenceRegistry.register(t, serverId);
   const parts: string[] = [];
-  if (t.name) parts.push(sanitizeLabel(t.name, STUB_FIELD_CHARS));
+  // A label is shown only when something is left of it once sanitized.
+  const name = t.name ? sanitizeLabel(t.name, STUB_FIELD_CHARS) : '';
+  if (name) parts.push(name);
   const meta: string[] = [];
-  if (t.mimeType) meta.push(sanitizeLabel(t.mimeType, STUB_FIELD_CHARS));
+  const mimeType = referenceTypeLabel(t.mimeType);
+  if (mimeType) meta.push(mimeType);
   if (t.sizeBytes !== undefined) meta.push(`${formatSizeBytes(t.sizeBytes)} claimed`);
   if (meta.length) parts.push(meta.join(', '));
-  if (provenance) parts.push(sanitizeLabel(provenance, STUB_FIELD_CHARS));
+  const origin = provenance ? sanitizeLabel(provenance, STUB_FIELD_CHARS) : '';
+  if (origin) parts.push(origin);
   if (record.fetchedPath) {
     // Already materialized by the host-mediated fetcher: hand the model the
     // workspace path (host-generated, §7.3) so existing tools just work.
     parts.push(`saved: ${sanitizeLabel(record.fetchedPath, 256)}`);
   } else {
-    parts.push('fetch with fetch_reference');
+    // An expired reference says so rather than inviting a fetch_reference
+    // call the fetcher can only refuse.
+    const expiry = referenceExpiry(record.testimony);
+    parts.push(expiry ? EXPIRY_REASON[expiry] : 'fetch with fetch_reference');
   }
   return `[${record.refId}] ${parts.join(' — ') || 'referenced content'}`;
 }

package/src/mcpl/server-connection.ts

@@ -48,6 +48,28 @@ import type {
 import { McplMethod } from './types.js';
 import type { ToolLifecycleParams, ToolObserveRule } from './tool-lifecycle.js';
 
+/**
+ * Payload of the connection `'close'` event (third argument; the first two
+ * stay `(code, signal)` for existing listeners). Lets a host see WHY the
+ * link went down — in particular a WebSocket close code such as 4001 from
+ * a server that refused or expired the credential — so it can refresh what
+ * `accessProvider` will hand the next dial instead of replaying it.
+ */
+export interface McplConnectionCloseInfo {
+  /** Transport kind that closed; null when the connection never had one
+   *  (a disconnected stub torn down before its first reconnect). */
+  transport: McplTransport['kind'] | null;
+  /** WebSocket close code (e.g. 4001) or stdio child exit code; null when unknown. */
+  code: number | null;
+  /** Signal that ended a stdio child; null otherwise. */
+  signal: NodeJS.Signals | null;
+  /** WebSocket close reason, or a short description of the cause. */
+  reason?: string;
+  /** True when the host closed the link (`close()` / `reconnectAfterFailure()`),
+   *  false when the transport dropped unexpectedly. */
+  byHost: boolean;
+}
+
 /** Timeout for the initialize handshake in milliseconds.
  *  Spring Boot + JDA servers can take 5-10s to boot, so 30s is safe. */
 const INITIALIZE_TIMEOUT_MS = 30_000;
@@ -93,7 +115,7 @@ interface RequestOptions {
  * - `'channels-changed'`   — Server sent `channels/changed`
  * - `'channels-incoming'`  — Server sent `channels/incoming`
  * - `'error'`              — Connection-level error
- * - `'close'`              — Connection closed
+ * - `'close'`              — Connection closed: `(code, signal, info: McplConnectionCloseInfo)`
  * - `'connect-failed'`     — Initial connect failed; background retry scheduled
  * - `'reconnect-failed'`   — A background reconnect attempt failed; next retry scheduled
  * - `'reconnect'`          — Background reconnect succeeded
@@ -209,6 +231,9 @@ export class McplServerConnection extends EventEmitter {
    * observable even though its original promise has already been rejected. */
   private orphanedRequests = new Map<string | number, { method: string; renderParams?: Record<string, unknown> }>();
   private closed = false;
+  /** Set by `reconnectAfterFailure()` before it closes a live transport, so
+   *  the transport close handler reports that teardown as `byHost: true`. */
+  private hostCloseRequested = false;
   private closePromise: Promise<void> | null = null;
   private closeIncomplete = false;
   private reconnectPromise: Promise<void> | null = null;
@@ -864,7 +889,7 @@ export class McplServerConnection extends EventEmitter {
       if (this.reconnectPromise) await this.reconnectPromise;
       if (this.transport) await this.transport.close();
       this.closeIncomplete = false;
-      this.emit('close');
+      this.emit('close', null, null, this.closeInfoByHost());
     });
     this.closePromise = attempt;
     void attempt.catch(() => {
@@ -886,14 +911,26 @@ export class McplServerConnection extends EventEmitter {
       return;
     }
     if (this.transport) {
+      this.hostCloseRequested = true;
       await this.transport.close();
       return;
     }
     this.closed = true;
-    this.emit('close');
+    this.emit('close', null, null, this.closeInfoByHost());
     this.scheduleReconnect();
   }
 
+  /** 'close' payload for a host-initiated teardown (no transport close code). */
+  private closeInfoByHost(): McplConnectionCloseInfo {
+    return {
+      transport: this.transport?.kind ?? null,
+      code: null,
+      signal: null,
+      reason: 'closed by host',
+      byHost: true,
+    };
+  }
+
   /**
    * Schedule a background reconnection attempt.
    *
@@ -1285,6 +1322,7 @@ export class McplServerConnection extends EventEmitter {
    * and — when enabled — schedules a background reconnect.
    */
   private setupLifecycle(transport: McplTransport): void {
+    this.hostCloseRequested = false;
     transport.on('error', (err: Error) => {
       this.emit('error', new Error(`MCPL server "${this.id}" transport error: ${err.message}`));
     });
@@ -1306,7 +1344,20 @@ export class McplServerConnection extends EventEmitter {
         this.pendingRequests.clear();
         this.orphanedRequests.clear();
 
-        this.emit('close', info.code ?? null, info.signal ?? null);
+        // Forward the transport's close info so listeners can tell a server
+        // that refused the credential (WebSocket 4001) from a crash, and act
+        // before the reconnect below redials. A teardown the host asked for
+        // via reconnectAfterFailure() arrives here too; report it as such.
+        const byHost = this.hostCloseRequested;
+        this.hostCloseRequested = false;
+        const closeInfo: McplConnectionCloseInfo = {
+          transport: transport.kind,
+          code: info.code ?? null,
+          signal: info.signal ?? null,
+          reason: info.reason ?? (byHost ? 'closed by host' : undefined),
+          byHost,
+        };
+        this.emit('close', closeInfo.code, closeInfo.signal, closeInfo);
 
         // Schedule reconnect if enabled (unexpected disconnect triggers auto-reconnect)
         if (this.reconnectEnabled) {

package/src/module-registry.ts

@@ -26,6 +26,12 @@ import type {
 import type { Agent } from './agent.js';
 import { DEFAULT_SHUTDOWN_TIMEOUT_MS, validateShutdownTimeout, waitForShutdown } from './shutdown.js';
 
+/** How the registry queues a module's event: its push names the module. A
+ * `ProcessQueue` serves too, ignoring the name. */
+export interface ModuleQueue {
+  push(event: ProcessEvent, moduleName?: string): void;
+}
+
 const MODULE_STATE_PREFIX = 'modules/';
 
 /**
@@ -78,7 +84,7 @@ export class ModuleRegistry {
   private moduleContexts: Map<string, ModuleContextImpl> = new Map();
   private speechHandlers: SpeechHandler[] = [];
   private store: JsStore;
-  private queue: ProcessQueue;
+  private queue: ModuleQueue;
   private getAgents: () => Agent[];
   private addMessageFn: (participant: string, content: ContentBlock[], metadata?: MessageMetadata) => MessageId;
   private editMessageFn: (id: MessageId, content: ContentBlock[]) => void;
@@ -86,7 +92,7 @@ export class ModuleRegistry {
   private getMessageFn: (id: MessageId) => StoredMessage | null;
   private queryMessagesFn: (filter: MessageQuery) => MessageQueryResult;
 
-  private pushEventFn: (event: ProcessEvent) => void;
+  private pushEventFn: (event: ProcessEvent, moduleName?: string) => void;
   private onTraceFn: (listener: TraceEventListener) => () => void;
   private callToolFn: (call: ToolCall) => Promise<ToolResult>;
   /** Framework ops-alert channel, surfaced to modules via
@@ -101,7 +107,7 @@ export class ModuleRegistry {
 
   constructor(
     store: JsStore,
-    queue: ProcessQueue,
+    queue: ModuleQueue,
     options: {
       getAgents: () => Agent[];
       addMessage: (participant: string, content: ContentBlock[], metadata?: MessageMetadata) => MessageId;
@@ -109,7 +115,8 @@ export class ModuleRegistry {
       removeMessage: (id: MessageId) => void;
       getMessage: (id: MessageId) => StoredMessage | null;
       queryMessages: (filter: MessageQuery) => MessageQueryResult;
-      pushEvent: (event: ProcessEvent) => void;
+      /** Called with the pushing module's name. */
+      pushEvent: (event: ProcessEvent, moduleName?: string) => void;
       onTrace: (listener: TraceEventListener) => () => void;
       callTool: (call: ToolCall) => Promise<ToolResult>;
       notifyOps?: (kind: string, agentName: string, message: string, data?: Record<string, unknown>) => void;
@@ -537,7 +544,7 @@ class ModuleContextImpl implements ModuleContext {
   private removeMessageFn: (id: MessageId) => void;
   private getMessageFn: (id: MessageId) => StoredMessage | null;
   private queryMessagesFn: (filter: MessageQuery) => MessageQueryResult;
-  private pushEventFn: (event: ProcessEvent) => void;
+  private pushEventFn: (event: ProcessEvent, moduleName?: string) => void;
   private onTraceFn: (listener: TraceEventListener) => () => void;
   private callToolFn: (call: ToolCall) => Promise<ToolResult>;
 
@@ -548,7 +555,7 @@ class ModuleContextImpl implements ModuleContext {
     moduleName: string,
     store: JsStore,
     stateId: string,
-    queue: ProcessQueue,
+    queue: ModuleQueue,
     registry: ModuleRegistry,
     isRestart: boolean,
     getAgents: () => Agent[],
@@ -557,14 +564,15 @@ class ModuleContextImpl implements ModuleContext {
     removeMessage: (id: MessageId) => void,
     getMessage: (id: MessageId) => StoredMessage | null,
     queryMessages: (filter: MessageQuery) => MessageQueryResult,
-    pushEvent: (event: ProcessEvent) => void,
+    pushEvent: (event: ProcessEvent, moduleName?: string) => void,
     onTrace: (listener: TraceEventListener) => () => void,
     callTool: (call: ToolCall) => Promise<ToolResult>
   ) {
     this.moduleName = moduleName;
     this.store = store;
     this.stateId = stateId;
-    this.queue = queue;
+    // The deprecated handle: a push names this module, as pushEvent() does.
+    this.queue = { push: (event) => queue.push(event, moduleName) };
     this.registry = registry;
     this.isRestart = isRestart;
     this.getAgentsFn = getAgents;
@@ -747,7 +755,7 @@ class ModuleContextImpl implements ModuleContext {
   }
 
   pushEvent(event: ProcessEvent): void {
-    this.pushEventFn(event);
+    this.pushEventFn(event, this.moduleName);
   }
 
   private persistExternalIdMap(): void {

package/src/modules/workspace/index.ts

@@ -39,7 +39,7 @@ import { MountWatcher, type FsChange } from './watcher.js';
 import { hashContent, DEFAULT_MAX_FILE_SIZE } from './sync.js';
 import { DiskAgreement, sameRootIdentity } from './disk-agreement.js';
 import { BranchIntents } from './branch-intent.js';
-import { filesystemTrustsCtime, locateRoot } from './observe.js';
+import { coveredByIgnore, filesystemTrustsCtime, locateRoot } from './observe.js';
 import { TOOL_BATCH_HOOK_TIMEOUT_MS } from '../../module-registry.js';
 import {
   type MountRuntime,
@@ -1220,7 +1220,14 @@ export class WorkspaceModule implements Module {
           + 'A mount whose root is not the directory disk last agreed with (an unmounted drive, a replaced '
           + 'directory) is unavailable and listed under `incomplete`. Reconnect the drive; acceptRoot is for a '
           + 'directory replaced on purpose, or a drive back under a new device number, never for one still '
-          + 'unplugged, whose empty mountpoint would become the root.',
+          + 'unplugged, whose empty mountpoint would become the root. What the scan passed over by design and '
+          + 'reported nowhere else is counted under `passedOver`, by mount and reason: entries the mount\'s '
+          + 'ignore list covers that hold nothing the workspace tracks (an ignored directory counts once). So a '
+          + 'total of 0, with no conflicts and nothing under `passedOver`, `incomplete` or `skipped`, means the '
+          + 'sync looked everywhere and nothing had changed. A path the mount ignores is synced when you name '
+          + 'it, and listed under `ignored`: a sync without a path passes over it. Naming an ignored directory '
+          + 'sets aside the patterns that cover it or a directory above it; one that covers only something '
+          + 'inside it still applies, and what it covers is passed over.',
         inputSchema: {
           type: 'object' as const,
           properties: {
@@ -2313,7 +2320,9 @@ export class WorkspaceModule implements Module {
         };
       }
 
-      return { success: true, data: { path: input.path, deleted: true } };
+      // Its whole receipt is what it changed: kept in the stub if the guard
+      // withholds the result (agent-framework #277).
+      return { success: true, data: { path: input.path, deleted: true }, keepWhenWithheld: ['path', 'deleted'] };
     });
   }
 
@@ -2761,6 +2770,10 @@ export class WorkspaceModule implements Module {
           : {}),
         ...(blocked.length > 0 ? { skipped: blocked } : {}),
       },
+      // What disk lost, then what it was written: kept in the stub if the
+      // guard withholds the result (agent-framework #277). What was left or
+      // skipped, and why, is in the full result.
+      keepWhenWithheld: ['deleted', 'materialized'],
     };
   }
 
@@ -2811,6 +2824,8 @@ export class WorkspaceModule implements Module {
     }> = [];
     const allSkipped: Array<{ mount: string; path: string; reason: string }> = [];
     const allIncomplete: Array<{ mount: string; path: string; reason: string }> = [];
+    const allPassedOver: Array<{ mount: string; reason: string; count: number }> = [];
+    const allIgnored: Array<{ mount: string; path: string; note: string }> = [];
     const rootsAccepted: string[] = [];
     if (input.acceptRoot && input.path) {
       return { success: false, error: 'acceptRoot takes a whole mount\'s root: give mount, or nothing, not path', isError: true };
@@ -2845,7 +2860,9 @@ export class WorkspaceModule implements Module {
           store.treeList(mount.treeStateId, prefix).length > 0 ||
           this.agreementOrThrow().paths(name, relativePath).some(([p]) => p.startsWith(prefix)) ||
           this.intents.get(name)!.list(relativePath).some(([p]) => p.startsWith(prefix));
-        const opts: PassOptions = { rehash: true, adopt: () => true, branchId: askedOn };
+        // named: ignore patterns covering the path asked for don't apply
+        // beneath it (a directory scope's walk; a path scope doesn't walk).
+        const opts: PassOptions = { rehash: true, adopt: () => true, branchId: askedOn, named: true };
         if (!isDir) return this.passUnlocked(mount, { kind: 'paths', paths: [relativePath] }, opts);
         const beneath = await this.passUnlocked(mount, { kind: 'dir', dir: relativePath, recursive: true }, opts);
         // Something at the path itself is no part of a directory scope: a file
@@ -2860,12 +2877,15 @@ export class WorkspaceModule implements Module {
           || this.intents.get(name)!.get(relativePath) !== null;
         if (!atPath) return beneath;
         const itself = await this.passUnlocked(mount, { kind: 'paths', paths: [relativePath] }, opts);
+        const passedOver = new Map(beneath.passedOver);
+        for (const [reason, count] of itself.passedOver) passedOver.set(reason, (passedOver.get(reason) ?? 0) + count);
         return {
           ops: [...beneath.ops, ...itself.ops],
           discarded: [...beneath.discarded, ...itself.discarded],
           newConflicts: [...beneath.newConflicts, ...itself.newConflicts],
           reports: new Map([...beneath.reports, ...itself.reports]),
           incomplete: [...beneath.incomplete, ...itself.incomplete],
+          passedOver,
           dirs: beneath.dirs,
           branchId: itself.branchId ?? beneath.branchId,
         };
@@ -2892,6 +2912,17 @@ export class WorkspaceModule implements Module {
         }
       }
       for (const region of pass.incomplete) allIncomplete.push({ mount: name, ...region });
+      for (const [reason, count] of pass.passedOver) allPassedOver.push({ mount: name, reason, count });
+      // A path named explicitly is synced even where the mount's ignore list
+      // covers it, and the result says so: a sync without a path passes
+      // over it, so nothing else keeps it current (agent-framework #276).
+      if (coveredByIgnore(relativePath, mount.config.ignore ?? [])) {
+        allIgnored.push({
+          mount: name,
+          path: relativePath,
+          note: 'this mount\'s ignore list covers it, so a sync without a path won\'t maintain it',
+        });
+      }
     }
 
     return {
@@ -2902,8 +2933,17 @@ export class WorkspaceModule implements Module {
         totalConflicts: allResults.reduce((sum, r) => sum + r.conflicts.length, 0),
         ...(allSkipped.length > 0 ? { skipped: allSkipped } : {}),
         ...(allIncomplete.length > 0 ? { incomplete: allIncomplete } : {}),
+        ...(allPassedOver.length > 0 ? { passedOver: allPassedOver } : {}),
+        ...(allIgnored.length > 0 ? { ignored: allIgnored } : {}),
         ...(rootsAccepted.length > 0 ? { rootsAccepted } : {}),
       },
+      // What the workspace took from disk, gave up, or now holds as a
+      // conflict, per mount, and any root it accepted: kept in the stub if
+      // the guard withholds the result (agent-framework #277). What the scan
+      // skipped or couldn't see is in the full result.
+      // A root it accepted is short and telling: first, so a long results
+      // list can't cut it away.
+      keepWhenWithheld: ['rootsAccepted', 'results'],
     };
   }
 

package/src/modules/workspace/observe.ts

@@ -494,7 +494,9 @@ export async function observePath(view: MountView, rootReal: string, relativePat
       return { kind: 'unobserved', reason: `a symlink that cannot be resolved (${errno(err) ?? String(err)})` };
     }
     if (!contained(rootReal, real)) return { kind: 'unobserved', reason: 'a symlink that leaves the mount' };
-    if (!target.isFile()) return { kind: 'unobserved', reason: 'not a regular file' };
+    if (!target.isFile()) {
+      return { kind: 'unobserved', reason: target.isDirectory() ? 'a symlink to a directory, not walked' : 'not a regular file' };
+    }
     info = target;
   } else if (info.isDirectory()) {
     return { kind: 'unobserved', reason: 'a directory' };
@@ -682,12 +684,27 @@ export interface Walk {
   missing: Set<string>;
   /**
    * Where the walk didn't reach, and why. `error` and `cap` regions may hide
-   * files the listing would show; `ignored` and `symlink` ones matter only
-   * where tracked entries lie beneath them.
+   * files the listing would show. An `ignored` region is passed over by
+   * design: one that hides a tracked entry is reported as incomplete, and
+   * one that hides nothing is counted as passed over. A `symlink` region is
+   * never walked; the pass reports the link itself by path.
    */
   incomplete: Array<{ path: string; reason: string; kind: 'error' | 'cap' | 'ignored' | 'symlink' }>;
 }
 
+/**
+ * Whether a mount's ignore list covers a mount-relative path: the path itself
+ * or any directory above it, as the walk's own test reads each entry by its
+ * path and name.
+ */
+export function coveredByIgnore(relativePath: string, patterns: string[]): boolean {
+  const segments = relativePath.split('/').filter(Boolean);
+  for (let i = 0; i < segments.length; i++) {
+    if (isIgnored(segments.slice(0, i + 1).join('/'), segments[i]!, patterns)) return true;
+  }
+  return false;
+}
+
 /** Simple ignore patterns, as the watcher and the old walk read them. */
 export function isIgnored(relativePath: string, name: string, patterns: string[]): boolean {
   for (const pattern of patterns) {
@@ -729,7 +746,10 @@ async function checkChild(view: MountView, rootReal: string, parent: CheckedDir,
  * the directory at its path: a directory moved or replaced meanwhile is an
  * incomplete region, contributing no names and proving nothing absent.
  */
-export async function walkScope(view: MountView, rootReal: string, scope: string, recursive: boolean, cap: number): Promise<Walk> {
+export async function walkScope(
+  view: MountView, rootReal: string, scope: string, recursive: boolean, cap: number,
+  opts: { named?: boolean } = {},
+): Promise<Walk> {
   const walk: Walk = { files: new Set(), dirs: new Set(), others: new Map(), complete: new Set(), missing: new Set(), incomplete: [] };
   const top = await checkDir(view, rootReal, scope);
   if (top.kind === 'absent') {
@@ -741,6 +761,12 @@ export async function walkScope(view: MountView, rootReal: string, scope: string
     return walk;
   }
   let capped = false;
+  // A scope a path sync names is walked even where the ignore list covers
+  // it: a pattern covering the scope itself, or a directory above it, doesn't
+  // apply beneath it. So a named directory's contents are synced, as a named
+  // file is (agent-framework #276). A listing keeps the ignore: its pass
+  // would otherwise start tracking what it lists.
+  const ignore = opts.named ? view.ignore.filter((pattern) => !coveredByIgnore(scope, [pattern])) : view.ignore;
 
   const visit = async (dir: CheckedDir): Promise<void> => {
     const rel = dir.rel;
@@ -770,7 +796,7 @@ export async function walkScope(view: MountView, rootReal: string, scope: string
     let reachedCap = false;
     for (const entry of entries) {
       const childRel = rel ? `${rel}/${entry.name}` : entry.name;
-      if (isIgnored(childRel, entry.name, view.ignore)) {
+      if (isIgnored(childRel, entry.name, ignore)) {
         others.push([childRel, 'ignored by the mount']);
         regions.push({ path: childRel, reason: 'ignored by the mount', kind: 'ignored' });
         continue;