@sema-agent/core 2.0.0 → 2.1.0

package/dist/stores/file/memory-store.js

@@ -3,6 +3,7 @@ import { uuidv7 } from "../../internal/harness.js";
 import { firstSentence, lexicalSearchMatch, } from "../../core/memory.js";
 import { cosineDistance, jaccardDistance, termSet } from "../../core/memory-vector.js";
 import { canonicalStoreKey, AppendLog, atomicWriteFile, ensureDir, readJsonlRecords, sanitizeScope, } from "./fs-atomic.js";
+const MAX_OPEN_MEMORY_SCOPES = 64;
 const sharedMemoryDirs = new Map();
 export class FileMemoryStore {
     root;
@@ -25,7 +26,7 @@ export class FileMemoryStore {
             this.sharedScopes = live;
         }
         else {
-            this.sharedScopes = { scopes: new Map(), refs: 1 };
+            this.sharedScopes = { scopes: new Map(), refs: 1, openLogs: new Set() };
             sharedMemoryDirs.set(this.scopeKey, this.sharedScopes);
         }
         this.tmpDir = join(root, "tmp");
@@ -90,11 +91,36 @@ export class FileMemoryStore {
                 vectors.set(ve.id, { embedding: ve.embedding, h: typeof ve.h === "string" ? ve.h : "" });
             }
         }
-        const state = { entries, log: new AppendLog(notesPath), dir, cursor, vectors, vlog: new AppendLog(vpath) };
+        const state = { entries, log: new AppendLog(notesPath), dir, cursor, vectors, vpath };
         this.scopes.set(scope, state);
+        this.touchOpenLogs(scope);
         return state;
     }
-    queueEmbed(state, id, body) {
+    touchOpenLogs(scope) {
+        const open = this.sharedScopes.openLogs;
+        open.delete(scope);
+        open.add(scope);
+        while (open.size > MAX_OPEN_MEMORY_SCOPES) {
+            const coldest = open.values().next().value;
+            if (coldest === undefined)
+                break;
+            open.delete(coldest);
+            const st = this.scopes.get(coldest);
+            st?.log.closeForSwap();
+            st?.vlog?.closeForSwap();
+        }
+    }
+    writeLog(scope, state) {
+        this.touchOpenLogs(scope);
+        return state.log;
+    }
+    vectorLog(scope, state) {
+        if (state.vlog === undefined)
+            state.vlog = new AppendLog(state.vpath);
+        this.touchOpenLogs(scope);
+        return state.vlog;
+    }
+    queueEmbed(scope, state, id, body) {
         const emb = this.embedder;
         if (!emb)
             return;
@@ -111,7 +137,7 @@ export class FileMemoryStore {
             const cur = state.entries.find((e) => e.id === id);
             if (!cur || hashBody(cur.text) !== h)
                 return;
-            state.vlog.append({ id, embedding: vec, h }, false);
+            this.vectorLog(scope, state).append({ id, embedding: vec, h }, false);
             state.vectors.set(id, { embedding: vec, h });
         })
             .catch(() => { });
@@ -155,14 +181,14 @@ export class FileMemoryStore {
     }
     commit(scope, entry) {
         const state = this.scopeState(scope);
-        state.log.append({ op: "append", entry }, true);
+        this.writeLog(scope, state).append({ op: "append", entry }, true);
         state.entries.push(entry);
         this.writeProjection(state);
-        this.queueEmbed(state, entry.id, entry.text);
+        this.queueEmbed(scope, state, entry.id, entry.text);
     }
     clear(scope) {
         const state = this.scopeState(scope);
-        state.log.append({ op: "clear" }, true);
+        this.writeLog(scope, state).append({ op: "clear" }, true);
         state.entries.length = 0;
         state.cursor = undefined;
         state.vectors.clear();
@@ -173,7 +199,7 @@ export class FileMemoryStore {
     }
     setConsolidationCursor(scope, cursor) {
         const state = this.scopeState(scope);
-        state.log.append({ op: "cursor", cursor }, true);
+        this.writeLog(scope, state).append({ op: "cursor", cursor }, true);
         state.cursor = cursor;
     }
     search(scope, query, limit = 10) {
@@ -241,20 +267,20 @@ export class FileMemoryStore {
         const ev = { op: "update", id, text: newBody, ts };
         if (newDesc !== undefined)
             ev.description = newDesc;
-        state.log.append(ev, true);
+        this.writeLog(scope, state).append(ev, true);
         entry.text = newBody;
         entry.ts = ts;
         entry.description = newDesc;
         this.writeProjection(state);
         state.vectors.delete(id);
-        this.queueEmbed(state, id, newBody);
+        this.queueEmbed(scope, state, id, newBody);
     }
     delete(scope, id) {
         const state = this.scopeState(scope);
         const i = state.entries.findIndex((e) => e.id === id);
         if (i === -1)
             return;
-        state.log.append({ op: "delete", id }, true);
+        this.writeLog(scope, state).append({ op: "delete", id }, true);
         state.entries.splice(i, 1);
         this.writeProjection(state);
     }
@@ -269,8 +295,9 @@ export class FileMemoryStore {
             sharedMemoryDirs.delete(this.scopeKey);
         for (const s of this.scopes.values()) {
             s.log.close();
-            s.vlog.close();
+            s.vlog?.close();
         }
+        this.sharedScopes.openLogs.clear();
     }
 }
 function renderBullet(e) {

package/dist/stores/file/tool-result-store.js

@@ -1,5 +1,7 @@
+import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import { assertSafeToolResultRef } from "../../core/tool-result-store.js";
 import { ensureDir, sanitizePathComponent, writeThenLink } from "./fs-atomic.js";
 export class FileToolResultStore {
     dir;
@@ -8,9 +10,11 @@ export class FileToolResultStore {
         ensureDir(this.dir);
     }
     pathFor(ref) {
-        return join(this.dir, `${sanitizePathComponent(ref)}.txt`);
+        assertSafeToolResultRef(ref);
+        return join(this.dir, `${sanitizePathComponent(encodeRefFilename(ref))}.txt`);
     }
     put(ref, content) {
+        assertSafeToolResultRef(ref);
         try {
             writeThenLink(this.pathFor(ref), content);
         }
@@ -28,8 +32,10 @@ export class FileToolResultStore {
         catch (err) {
             if (err.code === "ENOENT")
                 return undefined;
-            if (err instanceof Error && err.message.startsWith("file store: unsafe path component"))
+            if (err instanceof Error &&
+                (err.message.startsWith("file store: unsafe path component") || err.message.startsWith("tool-result store: unsafe ref"))) {
                 return undefined;
+            }
             throw err;
         }
         const offset = Math.min(full.length, Math.max(0, intOr(opts?.offset, 0)));
@@ -38,6 +44,14 @@ export class FileToolResultStore {
         return { content, offset, totalChars: full.length };
     }
 }
+const NATIVE_FILENAME_CHARSET = /^[A-Za-z0-9_.-]+$/;
+const MAX_FILENAME_CHARS = 180;
+function encodeRefFilename(ref) {
+    if (ref.length <= MAX_FILENAME_CHARS && NATIVE_FILENAME_CHARSET.test(ref))
+        return ref;
+    const base = ref.replace(/[^A-Za-z0-9_.-]/g, "-").slice(0, 64);
+    return `${base || "ref"}-${createHash("sha256").update(ref, "utf8").digest("hex")}`;
+}
 function intOr(x, fallback) {
     return Number.isFinite(x) ? Math.floor(x) : fallback;
 }

package/dist/stores/file/workflow-journal-store.d.ts

@@ -1,8 +1,10 @@
 import { type WorkflowJournalEntry, type WorkflowJournalStore } from "../../core/workflow-journal-store.js";
 export { MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "../../core/workflow-journal-store.js";
+export declare const RESUME_CLAIM_TTL_MS: number;
 export declare class FileWorkflowJournalStore implements WorkflowJournalStore {
     private readonly fsyncEnabled;
     private readonly dir;
+    private readonly claimsDir;
     private readonly shared;
     private readonly sharedKey;
     private closed;
@@ -14,6 +16,21 @@ export declare class FileWorkflowJournalStore implements WorkflowJournalStore {
     private replay;
     append(runId: string, scope: string, entry: WorkflowJournalEntry): Promise<void>;
     load(runId: string, scope: string): Promise<WorkflowJournalEntry[]>;
+    private claimPathFor;
+    private readClaim;
+    resumeClaim(input: {
+        sourceRunId: string;
+        newRunId: string;
+        scope: string;
+    }): Promise<{
+        granted: boolean;
+        holder?: string;
+    }>;
+    releaseResumeClaim(input: {
+        sourceRunId: string;
+        newRunId: string;
+        scope: string;
+    }): Promise<void>;
     deleteByRun(runId: string): Promise<number>;
     dispose(): void;
 }

package/dist/stores/file/workflow-journal-store.js

@@ -1,14 +1,18 @@
-import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, unlinkSync, writeSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { callKeyOrdinal } from "../../core/workflow-journal-store.js";
 import { AppendLog } from "./fs-atomic.js";
 import { canonicalStoreKey, sanitizePathComponent } from "./fs-atomic.js";
 import { oversizeJournalResult } from "../../core/workflow-journal-store.js";
 export { MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "../../core/workflow-journal-store.js";
+export const RESUME_CLAIM_TTL_MS = 60 * 60 * 1000;
 const sharedJournalDirs = new Map();
+const MAX_OPEN_JOURNAL_LOGS = 64;
 export class FileWorkflowJournalStore {
     fsyncEnabled;
     dir;
+    claimsDir;
     shared;
     sharedKey;
     closed = false;
@@ -22,6 +26,7 @@ export class FileWorkflowJournalStore {
         this.fsyncEnabled = fsyncEnabled;
         this.dir = join(root, "workflow-journal");
         mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+        this.claimsDir = join(this.dir, "claims");
         this.sharedKey = canonicalStoreKey(this.dir);
         const existing = sharedJournalDirs.get(this.sharedKey);
         if (existing !== undefined) {
@@ -87,7 +92,22 @@ export class FileWorkflowJournalStore {
         let log = this.logs.get(runId);
         if (log === undefined) {
             log = new AppendLog(this.pathFor(runId));
-            this.logs.set(runId, log);
+        }
+        else {
+            this.logs.delete(runId);
+        }
+        this.logs.set(runId, log);
+        while (this.logs.size > MAX_OPEN_JOURNAL_LOGS) {
+            const coldest = this.logs.keys().next().value;
+            if (coldest === undefined || coldest === runId)
+                break;
+            const stale = this.logs.get(coldest);
+            this.logs.delete(coldest);
+            try {
+                stale?.close();
+            }
+            catch {
+            }
         }
         const line = { scope, ordinal: callKeyOrdinal(entry.callKey), callKey: entry.callKey, result: entry.result };
         log.append(line, this.fsyncEnabled);
@@ -98,6 +118,86 @@ export class FileWorkflowJournalStore {
             return [];
         return [...rec.byOrdinal.entries()].sort((a, b) => a[0] - b[0]).map(([, e]) => e);
     }
+    claimPathFor(sourceRunId, scope) {
+        const scopeTag = createHash("sha256").update(scope).digest("hex").slice(0, 16);
+        return join(this.claimsDir, `${sanitizePathComponent(sourceRunId)}.${scopeTag}.json`);
+    }
+    readClaim(path) {
+        if (!existsSync(path))
+            return undefined;
+        try {
+            const rec = JSON.parse(readFileSync(path, "utf8"));
+            if (typeof rec.holder !== "string" || typeof rec.expiresAt !== "number" || !Number.isFinite(rec.expiresAt)) {
+                return undefined;
+            }
+            return rec;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async resumeClaim(input) {
+        const { sourceRunId, newRunId, scope } = input;
+        let path;
+        try {
+            path = this.claimPathFor(sourceRunId, scope);
+        }
+        catch {
+            return { granted: true };
+        }
+        mkdirSync(this.claimsDir, { recursive: true, mode: 0o700 });
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const record = { sourceRunId, holder: newRunId, expiresAt: Date.now() + RESUME_CLAIM_TTL_MS };
+            try {
+                const fd = openSync(path, "wx", 0o600);
+                try {
+                    writeSync(fd, JSON.stringify(record));
+                }
+                finally {
+                    closeSync(fd);
+                }
+                return { granted: true };
+            }
+            catch (err) {
+                if (err.code !== "EEXIST")
+                    throw err;
+            }
+            const existing = this.readClaim(path);
+            if (existing !== undefined && existing.holder === newRunId) {
+                return { granted: true };
+            }
+            if (existing === undefined || existing.expiresAt <= Date.now()) {
+                try {
+                    unlinkSync(path);
+                }
+                catch {
+                }
+                continue;
+            }
+            return { granted: false, holder: existing.holder };
+        }
+        const winner = this.readClaim(path);
+        if (winner === undefined || winner.holder === newRunId)
+            return { granted: true };
+        return { granted: false, holder: winner.holder };
+    }
+    async releaseResumeClaim(input) {
+        let path;
+        try {
+            path = this.claimPathFor(input.sourceRunId, input.scope);
+        }
+        catch {
+            return;
+        }
+        const existing = this.readClaim(path);
+        if (existing === undefined || existing.holder !== input.newRunId)
+            return;
+        try {
+            unlinkSync(path);
+        }
+        catch {
+        }
+    }
     async deleteByRun(runId) {
         const log = this.logs.get(runId);
         if (log !== undefined) {

package/dist/tools/fs/bash-readonly-classifier.js

@@ -159,7 +159,7 @@ export function classifyCompoundReadonly(command, allow) {
         const deviceArgs = toks.slice(1).filter((t) => !t.startsWith("-")).map(normalizeAbsPathLexically).filter(isBlockedDevicePath);
         const rescuedByHead = headBoundIsSmall(name, toks) && deviceArgs.every((d) => GENERATOR_DEVICES.has(d));
         if (!rescuedByHead && deviceArgs.length > 0) {
-            return "an unbounded device source (/dev/zero, /dev/stdin, /proc/<pid>/fd/0, …) would block the pipeline until the tool timeout — not auto-allowed";
+            return "reads a device/special file that is either unbounded (/dev/zero, /dev/stdin, /proc/<pid>/fd/0, … — blocks the pipeline until the tool timeout) or process-private (/proc/<pid>/environ, /proc/<pid>/mem, …) — not auto-allowed";
         }
     }
     return undefined;

package/dist/tools/fs/fs-read.js

@@ -250,10 +250,10 @@ export function createReadFileTool(env, state, rootCanonical, cwdRef, additional
             }
             const truncated = start > 1 || end < total || pageMarker !== undefined;
             const prev = state.get(r.key);
-            if (total > 0 && prev?.seededFromContext && start === 1 && effLimit === undefined && prev.hash === hash) {
+            if (total > 0 && prev?.seededFromContext && !prev.isPartialView && start === 1 && effLimit === undefined && prev.hash === hash) {
                 return seededFileUnchangedReminder(r.key);
             }
-            if (total > 0 && prev && prev.hash === hash && prev.view && prev.view.start === start && prev.view.end === end) {
+            if (total > 0 && prev && !prev.isPartialView && prev.hash === hash && prev.view && prev.view.start === start && prev.view.end === end) {
                 return `[${path}: unchanged since you last read it (lines ${start}-${end} of ${total}); content omitted to save context]`;
             }
             state.set(r.key, {

package/dist/tools/fs/fs-search-tools.js

@@ -151,6 +151,8 @@ export function createGlobTool(env, rootCanonical, additionalRoots) {
                 scoped = r.key;
             }
             const r2 = await runGlobDetailed(env, rootCanonical, pattern, { path: scoped, max: max_results }, ctx.signal);
+            if (r2.error !== undefined)
+                return errorResult(r2.error);
             return {
                 content: r2.text,
                 details: { type: "glob", filenames: r2.filenames, numFiles: r2.numFiles, truncated: r2.truncated, durationMs: r2.durationMs, totalMatches: r2.totalMatches, countIsComplete: r2.countIsComplete },
@@ -162,7 +164,7 @@ export const HAND_TOOL_EFFECTS = {
     Read: "read",
     Edit: "write",
     MultiEdit: "write",
-    Write: "idempotent",
+    Write: "write",
     NotebookEdit: "write",
     Grep: "read",
     Glob: "read",

package/dist/tools/fs/fs-shared.d.ts

@@ -18,7 +18,8 @@ export declare function persistedTextOf(encoded: string | Uint8Array): string;
 export declare function notReadRefusalText(env: ExecutionEnv, toolName: string, key: string, v: {
     code: string;
     message: string;
-}, signal?: AbortSignal): Promise<string>;
+    partialView?: boolean;
+}, signal?: AbortSignal, fallbackHint?: string): Promise<string>;
 export declare const MAX_IMAGE_READ_BYTES: number;
 export declare const MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES: number;
 export type ReadImageDownsamplerOption = ImageDownsampler | false | undefined;

package/dist/tools/fs/fs-shared.js

@@ -1,6 +1,6 @@
 import { Type } from "typebox";
 import { clipWithFilePointer } from "../../core/tool-errors.js";
-import { sha256, similarNameSuggestion, OVERSIZE_READ_ESCAPE_HINT, } from "./safety.js";
+import { sha256, similarNameSuggestion, OVERSIZE_READ_ESCAPE_HINT, PARTIAL_VIEW_READ_ESCAPE_HINT, } from "./safety.js";
 import { decodeTextBytes, normalizeFileText } from "./encoding.js";
 import { shellQuote } from "./search.js";
 import { isNotebookPath } from "./notebook.js";
@@ -30,10 +30,14 @@ export function decodeEditBytes(bytes, path) {
 export function persistedTextOf(encoded) {
     return decodeTextBytes(typeof encoded === "string" ? Buffer.from(encoded, "utf8") : encoded).text;
 }
-export async function notReadRefusalText(env, toolName, key, v, signal) {
+export async function notReadRefusalText(env, toolName, key, v, signal, fallbackHint) {
     const base = `Error (${toolName}): ${v.message}`;
+    if (v.partialView === true && !isNotebookPath(key))
+        return `${base} ${PARTIAL_VIEW_READ_ESCAPE_HINT}`;
     const info = await env.fileInfo(key, signal);
-    return info.ok && info.value.kind !== "directory" && info.value.size > MAX_READ_BYTES && !isNotebookPath(key) ? `${base} ${OVERSIZE_READ_ESCAPE_HINT}` : base;
+    if (info.ok && info.value.kind !== "directory" && info.value.size > MAX_READ_BYTES && !isNotebookPath(key))
+        return `${base} ${OVERSIZE_READ_ESCAPE_HINT}`;
+    return fallbackHint === undefined ? base : `${base} ${fallbackHint}`;
 }
 export const MAX_IMAGE_READ_BYTES = 5 * 1024 * 1024;
 export const MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES = 64 * 1024 * 1024;

package/dist/tools/fs/fs-write.js

@@ -1,8 +1,8 @@
 import { randomUUID } from "node:crypto";
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
-import { sha256, resolveKey, violationText, requireRead, checkStale, checkEditMatch, checkNoChange, fileArgPath, resolveQuoteMatch, adaptNewStringQuotes, deletionOldString, countOccurrences, } from "./safety.js";
-import { decodeTextBytes, encodeTextForFile, normalizeEditText, normalizeFileText, splitLeadingBom } from "./encoding.js";
+import { sha256, resolveKey, violationText, requireRead, checkStale, checkEditMatch, checkNoChange, fileArgPath, resolveQuoteMatch, adaptNewStringQuotes, deletionOldString, countOccurrences, WRITE_ENCODING_DEADLOCK_ESCAPE_HINT, } from "./safety.js";
+import { decodeTextBytes, encodeTextForFile, normalizeEditText, normalizeFileText } from "./encoding.js";
 import { MAX_EDIT_BYTES, formatByteSize, decodeEditBytes, persistedTextOf, notReadRefusalText, enoentMessage, FILE_STATE_TRAILER, FILE_PATH_PARAMS, ipynbRedirect, countLines, } from "./fs-shared.js";
 async function gateToolWrite(hook, tool, path, key, content) {
     if (hook === undefined)
@@ -218,7 +218,7 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
             ...FILE_PATH_PARAMS,
             content: Type.String({ description: "The content to write to the file" }),
         }),
-        effect: "idempotent",
+        effect: "write",
         execute: async (args, ctx) => {
             const { content } = args;
             const path = fileArgPath(args);
@@ -237,8 +237,7 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
             if (exists.value) {
                 const notRead = requireRead(state, r.key);
                 if (notRead) {
-                    return errorResult(`${violationText("Write", notRead)} ` +
-                        `(If the Read tool refuses this file (binary/unknown encoding), overwrite or convert it with bash instead — e.g. \`rm\` + rewrite, or \`iconv\`.)`);
+                    return errorResult(await notReadRefusalText(env, "Write", r.key, notRead, ctx.signal, WRITE_ENCODING_DEADLOCK_ESCAPE_HINT));
                 }
                 const readBin = await env.readBinaryFile(r.key, ctx.signal);
                 if (!readBin.ok)
@@ -253,16 +252,15 @@ export function createWriteFileTool(env, state, rootCanonical, cwdRef, additiona
                 const gated = await gateToolWrite(beforeWrite, "Write", path, r.key, content);
                 if (gated !== undefined)
                     return errorResult(gated);
-                const outgoing = splitLeadingBom(content);
-                const writeEncoding = outgoing.hadBom && !decodedPrev.encoding.hadBom ? { ...decodedPrev.encoding, hadBom: true } : decodedPrev.encoding;
-                const write = await env.writeFile(r.key, encodeTextForFile(outgoing.text, writeEncoding, "preserve"), ctx.signal);
+                const encodedWrite = encodeTextForFile(content, decodedPrev.encoding, "preserve");
+                const write = await env.writeFile(r.key, encodedWrite, ctx.signal);
                 if (!write.ok)
                     return errorResult(`Error (Write): cannot write "${path}": ${write.error.message}`);
-                const totalLines = countLines(outgoing.text);
-                state.set(r.key, { hash: sha256(normalizeFileText(content)), totalLines, truncated: false, lastReadAt: Date.now() });
+                const persistedWrite = persistedTextOf(encodedWrite);
+                state.set(r.key, { hash: sha256(persistedWrite), totalLines: countLines(persistedWrite), truncated: false, lastReadAt: Date.now() });
                 return {
                     content: `The file ${path} has been updated successfully.${FILE_STATE_TRAILER}`,
-                    details: { type: "update", filePath: path, content: normalizeFileText(content), originalFile },
+                    details: { type: "update", filePath: path, content: persistedWrite, originalFile },
                 };
             }
             const gatedCreate = await gateToolWrite(beforeWrite, "Write", path, r.key, content);

package/dist/tools/fs/safety.d.ts

@@ -17,6 +17,7 @@ export type ReadFileState = Map<string, ReadEntry>;
 export declare function sha256(content: string): string;
 export interface FsViolation {
     code: "path_not_in_root" | "not_read" | "stale" | "ambiguous_edit" | "invalid";
+    partialView?: true;
     message: string;
 }
 export declare function isBlockedDevicePath(key: string): boolean;
@@ -44,6 +45,8 @@ export declare function canonicalizeTarget(env: ExecutionEnv, path: string, sign
 export declare function violationText(toolName: string, v: FsViolation): string;
 export declare function requireRead(state: ReadFileState, key: string): FsViolation | undefined;
 export declare const OVERSIZE_READ_ESCAPE_HINT = "(This file is over the Read tool's whole-file byte cap, so a default Read is refused \u2014 read it in slices with explicit offset/limit to satisfy the read-first rule, or inspect/transform it with bash (e.g. `sed -n`, `grep`) instead.)";
+export declare const PARTIAL_VIEW_READ_ESCAPE_HINT = "(Your last Read of this file returned only a PARTIAL view \u2014 the output token cap paginated it, so a default Read will keep returning the same page. Re-read it with explicit offset/limit (start from the page marker's next-page hint) until you have seen the part you are about to change; an explicit slice that fits satisfies the read-first rule. Or inspect/transform it with bash (e.g. `sed -n`, `grep`) instead.)";
+export declare const WRITE_ENCODING_DEADLOCK_ESCAPE_HINT = "(If the Read tool refuses this file (binary/unknown encoding), overwrite or convert it with bash instead \u2014 e.g. `rm` + rewrite, or `iconv`.)";
 export declare function checkNoChange(oldString: string, newString: string): FsViolation | undefined;
 export declare function checkStale(entry: ReadEntry, currentHash: string): FsViolation | undefined;
 export declare function countOccurrences(haystack: string, needle: string): number;

package/dist/tools/fs/safety.js

@@ -38,17 +38,23 @@ const BLOCKED_DEVICE_PATHS = new Set([
     "/dev/stdin", "/dev/stdout", "/dev/stderr", "/dev/tty", "/dev/console",
     "/dev/fd/0", "/dev/fd/1", "/dev/fd/2",
 ]);
-const PROC_FD_RE = /^\/proc\/[^/]+\/fd\/[0-2]$/;
+function isProcStdioFd(key) {
+    return key.startsWith("/proc/") && (key.endsWith("/fd/0") || key.endsWith("/fd/1") || key.endsWith("/fd/2"));
+}
+const PROC_SENSITIVE_RE = /^\/proc\/[^/]+\/(environ|cmdline|auxv|maps|mem|stat)$/;
 const WIN_RESERVED_RE = /^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(\.[^\\/]*)?$/i;
+function isWinFormPath(p) {
+    return /^[A-Za-z]:[\\/]/.test(p) || p.startsWith("\\\\") || (!p.startsWith("/") && p.includes("\\"));
+}
 function isWinReservedDeviceKey(key) {
-    if (!(/^[A-Za-z]:[\\/]/.test(key) || key.startsWith("\\\\") || (!key.startsWith("/") && key.includes("\\"))))
+    if (!isWinFormPath(key))
         return false;
     const t = key.replace(/[\\/]+$/, "");
     const base = t.slice(Math.max(t.lastIndexOf("/"), t.lastIndexOf("\\")) + 1);
     return WIN_RESERVED_RE.test(base);
 }
 export function isBlockedDevicePath(key) {
-    return BLOCKED_DEVICE_PATHS.has(key) || PROC_FD_RE.test(key) || isWinReservedDeviceKey(key);
+    return BLOCKED_DEVICE_PATHS.has(key) || isProcStdioFd(key) || PROC_SENSITIVE_RE.test(key) || isWinReservedDeviceKey(key);
 }
 export function normalizeAbsPathLexically(p) {
     if (!p.startsWith("/"))
@@ -168,10 +174,11 @@ export async function resolveKey(env, rootCanonical, path, signal, baseCwd, addi
     return { ok: true, key };
 }
 export async function canonicalizeTarget(env, path, signal, baseCwd) {
-    if (isUncPath(path)) {
-        return { ok: false, message: `path "${path}" is a UNC/network path; refused (potential credential leak).` };
+    if (isUncPath(path) && isWinFormPath(path)) {
+        return { ok: true, key: path };
     }
-    const target = baseCwd && !isAbsolutePathForm(path) ? `${baseCwd.replace(/[\\/]+$/, "")}/${path}` : path;
+    const spelled = path.startsWith("//") ? path.replace(/^\/+/, "/") : path;
+    const target = baseCwd && !isAbsolutePathForm(spelled) ? `${baseCwd.replace(/[\\/]+$/, "")}/${spelled}` : spelled;
     const absR = await env.absolutePath(target, signal);
     if (!absR.ok)
         return { ok: false, message: `cannot resolve path "${path}": ${absR.error.message}` };
@@ -230,11 +237,17 @@ export function violationText(toolName, v) {
 export function requireRead(state, key) {
     const entry = state.get(key);
     if (entry === undefined || entry.isPartialView) {
-        return { code: "not_read", message: "File has not been read yet. Read it first before writing to it." };
+        return {
+            code: "not_read",
+            message: "File has not been read yet. Read it first before writing to it.",
+            ...(entry?.isPartialView ? { partialView: true } : {}),
+        };
     }
     return undefined;
 }
 export const OVERSIZE_READ_ESCAPE_HINT = "(This file is over the Read tool's whole-file byte cap, so a default Read is refused — read it in slices with explicit offset/limit to satisfy the read-first rule, or inspect/transform it with bash (e.g. `sed -n`, `grep`) instead.)";
+export const PARTIAL_VIEW_READ_ESCAPE_HINT = "(Your last Read of this file returned only a PARTIAL view — the output token cap paginated it, so a default Read will keep returning the same page. Re-read it with explicit offset/limit (start from the page marker's next-page hint) until you have seen the part you are about to change; an explicit slice that fits satisfies the read-first rule. Or inspect/transform it with bash (e.g. `sed -n`, `grep`) instead.)";
+export const WRITE_ENCODING_DEADLOCK_ESCAPE_HINT = "(If the Read tool refuses this file (binary/unknown encoding), overwrite or convert it with bash instead — e.g. `rm` + rewrite, or `iconv`.)";
 export function checkNoChange(oldString, newString) {
     if (oldString === newString) {
         return { code: "invalid", message: "No changes to make: old_string and new_string are exactly the same." };

package/dist/tools/fs/search.d.ts

@@ -69,4 +69,5 @@ export declare function runGlobDetailed(env: ExecutionEnv, root: string, pattern
     durationMs: number;
     totalMatches: number;
     countIsComplete: boolean;
+    error?: string;
 }>;

package/dist/tools/fs/search.js

@@ -1089,6 +1089,13 @@ export async function runGlobDetailed(env, root, pattern, opts = {}, signal) {
     const baseIgnore = await buildIgnore(env, root, signal);
     const rootPrefix = root.replace(/[\\/]+$/, "") + (root.includes("\\") ? "\\" : "/");
     const start = opts.path ? (opts.path.startsWith("/") || /^[A-Za-z]:[\\/]/.test(opts.path) ? opts.path : `${rootPrefix}${opts.path}`) : root;
+    if (opts.path !== undefined) {
+        const probe = await env.fileInfo(start, signal);
+        if (!probe.ok && probe.error.code === "not_found") {
+            const error = `Error (Glob): path ${JSON.stringify(opts.path)} does not exist — check the path, or omit \`path\` to search the whole root.`;
+            return { text: error, error, filenames: [], numFiles: 0, truncated: false, durationMs: Date.now() - t0, totalMatches: 0, countIsComplete: false };
+        }
+    }
     const pat = normalizeGlobToken(pattern);
     const anchored = globIsAnchored(pattern);
     const re = globTokenToRegExp(pat, anchored, true);
@@ -1131,6 +1138,7 @@ export async function runGlobDetailed(env, root, pattern, opts = {}, signal) {
         return k < starStarIdx ? literalAt[k] === segs[k] : literalAfterStarStar.has(segs[k]);
     };
     let ignoredDirs = 0;
+    let ignoredFiles = 0;
     const rescued = [];
     const ignore = (relPath, isDir) => {
         const sr = toStartRel(relPath);
@@ -1144,8 +1152,12 @@ export async function runGlobDetailed(env, root, pattern, opts = {}, signal) {
         if (rescued.length > 0 && rescued.some((r) => sr.startsWith(r)))
             return false;
         const ig = baseIgnore(relPath, isDir);
-        if (ig && isDir)
-            ignoredDirs++;
+        if (ig) {
+            if (isDir)
+                ignoredDirs++;
+            else
+                ignoredFiles++;
+        }
         return ig;
     };
     const walked = await walk(env, root, start, ignore, signal);
@@ -1173,6 +1185,12 @@ export async function runGlobDetailed(env, root, pattern, opts = {}, signal) {
     const ignoreNote = matched.length === 0 && ignoredDirs > 0
         ? `\n[note: ${ignoredDirs} ignored director${ignoredDirs === 1 ? "y was" : "ies were"} not searched (dependency/build/VCS trees and .gitignore) — name a directory in the pattern (e.g. "dist/**") or pass \`path\` to include it]`
         : "";
-    const text = matched.length === 0 ? "No files matched." + ignoreNote + caveat : matched.join("\n") + capNote + caveat;
+    const ignoredFileNote = matched.length === 0 && ignoredFiles > 0
+        ? `\n[note: ${ignoredFiles} file(s) matching an ignore rule (.gitignore) were skipped — an empty result here is NOT proof the file is absent; name it literally with a root-anchored path (e.g. "/notes.secret", "logs/app.log") to include it, or read it directly]`
+        : "";
+    const budgetNote = matched.length === 0 && walked.incomplete
+        ? `\n[note: the file-walk budget (${WALK_MAX_FILES} files / ${WALK_MAX_DEPTH} directory levels) ran out before the whole tree was scanned — this empty result is NOT proof the file is absent; scope the search with \`path\`, or use a root-anchored pattern (e.g. "src/**/*.ts") so the walk is pruned toward it, then retry]`
+        : "";
+    const text = matched.length === 0 ? "No files matched." + ignoreNote + ignoredFileNote + budgetNote + caveat : matched.join("\n") + capNote + caveat;
     return { text, filenames: matched, numFiles: matched.length, truncated, durationMs: Date.now() - t0, totalMatches, countIsComplete };
 }

package/dist/tools/task-list.d.ts

@@ -20,5 +20,6 @@ export interface TaskListStore {
 }
 export declare function normalizeTaskShape<T>(item: T): T;
 export declare function assertJsonMetadata(value: unknown, path?: string): void;
+export declare function compareTaskIds(a: string, b: string): number;
 export declare function createMemoryTaskListStore(): TaskListStore;
 export declare function createTaskListTools(store?: TaskListStore): ToolSpec[];