@sema-agent/server 7.140.0 → 7.142.0

package/dist/project-bundle.js

@@ -0,0 +1,609 @@
+import { Readable } from "node:stream";
+import { once } from "node:events";
+import { createGunzip, createGzip } from "node:zlib";
+export const PROJECT_BUNDLE_MIME = "application/vnd.sema.project-bundle";
+export function attachmentKindOf(mime) {
+    return mime === PROJECT_BUNDLE_MIME ? "project_bundle" : "attachment";
+}
+export const PROJECT_BUNDLE_INVALID_REASONS = ["not_archive", "unsafe_path", "entry_type", "reserved_path", "duplicate_path", "expanded_too_large", "too_many_entries"];
+export const PROJECT_BUNDLE_MAX_EXPANDED_BYTES = 512 * 1024 * 1024;
+export const PROJECT_BUNDLE_MAX_ENTRIES = 200_000;
+export const PROJECT_BUNDLE_RESERVED_TOP_LEVEL = [".git", "attachments"];
+class Refusal extends Error {
+    reason;
+    detail;
+    entryPath;
+    constructor(reason, detail, entryPath) {
+        super(detail);
+        this.reason = reason;
+        this.detail = detail;
+        this.entryPath = entryPath;
+    }
+}
+const BLOCK = 512;
+const PATH_MAX_BYTES = 4095;
+const NAME_MAX_BYTES = 255;
+const MAX_LINK_HOPS = 40;
+const YIELD_STEPS = 1 << 16;
+const META_MAX_BYTES = 1024 * 1024;
+const UTF8 = new TextDecoder("utf-8", { fatal: true });
+export async function readProjectBundle(bytes, opts = {}) {
+    const maxExpanded = opts.limits?.maxExpandedBytes ?? PROJECT_BUNDLE_MAX_EXPANDED_BYTES;
+    const maxEntries = opts.limits?.maxEntries ?? PROJECT_BUNDLE_MAX_ENTRIES;
+    const writer = opts.canonical === true ? createCanonicalWriter() : undefined;
+    const gunzip = createGunzip();
+    try {
+        const walk = new TarWalk(maxEntries, writer);
+        let expanded = 0;
+        for await (const chunk of Readable.from([Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)]).pipe(gunzip)) {
+            expanded += chunk.length;
+            if (expanded > maxExpanded)
+                throw new Refusal("expanded_too_large", `the bundle expands past ${maxExpanded} bytes`);
+            await walk.feed(chunk);
+            if (walk.done)
+                break;
+        }
+        const judged = await walk.finish();
+        const canonical = writer === undefined ? undefined : await writer.end();
+        return { ok: true, entries: judged.entries, topLevel: judged.topLevel, ...(canonical !== undefined ? { canonical } : {}) };
+    }
+    catch (e) {
+        writer?.abort();
+        if (e instanceof Refusal)
+            return { ok: false, reason: e.reason, ...(e.entryPath !== undefined ? { path: e.entryPath } : {}), detail: e.detail };
+        return { ok: false, reason: "not_archive", detail: `not a gzip-compressed tar: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    finally {
+        gunzip.destroy();
+    }
+}
+class TarWalk {
+    writer;
+    done = false;
+    chunks = [];
+    queued = 0;
+    entries = 0;
+    tree;
+    body;
+    pax = {};
+    unsupportedPax;
+    longName;
+    longLink;
+    zeroBlocks = 0;
+    constructor(maxEntries, writer) {
+        this.writer = writer;
+        this.tree = new BundleTree(maxEntries);
+    }
+    async feed(chunk) {
+        this.chunks.push(chunk);
+        this.queued += chunk.length;
+        for (;;) {
+            if (this.done)
+                return;
+            if (this.body !== undefined) {
+                if (!(await this.drainBody()))
+                    return;
+                continue;
+            }
+            if (this.queued < BLOCK)
+                return;
+            await this.header(this.take(BLOCK));
+        }
+    }
+    async finish() {
+        if (!this.done && (this.body !== undefined || this.queued !== 0))
+            throw new Refusal("not_archive", "the archive ends inside an entry");
+        await this.tree.judge();
+        return { entries: this.entries, topLevel: this.tree.topLevel() };
+    }
+    take(n) {
+        const out = Buffer.allocUnsafe(n);
+        let off = 0;
+        while (off < n) {
+            const head = this.chunks[0];
+            const k = Math.min(head.length, n - off);
+            head.copy(out, off, 0, k);
+            off += k;
+            if (k === head.length)
+                this.chunks.shift();
+            else
+                this.chunks[0] = head.subarray(k);
+        }
+        this.queued -= n;
+        return out;
+    }
+    async drainBody() {
+        const b = this.body;
+        while (b.remaining > 0) {
+            if (this.queued === 0)
+                return false;
+            const head = this.chunks[0];
+            const k = Math.min(head.length, b.remaining);
+            const part = head.subarray(0, k);
+            if (k === head.length)
+                this.chunks.shift();
+            else
+                this.chunks[0] = head.subarray(k);
+            this.queued -= k;
+            b.remaining -= k;
+            if (b.sink === "write")
+                await this.writer.content(part);
+            else if (b.sink === "meta")
+                b.meta.push(Buffer.from(part));
+        }
+        if (this.queued < b.pad)
+            return false;
+        if (b.pad > 0)
+            this.take(b.pad);
+        this.body = undefined;
+        if (b.sink === "write")
+            await this.writer.endContent();
+        if (b.sink === "meta")
+            this.applyMeta(b.metaKind, Buffer.concat(b.meta));
+        return true;
+    }
+    async header(h) {
+        if (h.every((x) => x === 0)) {
+            this.zeroBlocks++;
+            if (this.zeroBlocks >= 2)
+                this.done = true;
+            return;
+        }
+        if (this.zeroBlocks > 0)
+            throw new Refusal("not_archive", "a header follows the end-of-archive marker");
+        if (!checksumHolds(h))
+            throw new Refusal("not_archive", "a tar header's checksum does not hold");
+        const magic = h.toString("latin1", 257, 263);
+        const posix = magic === "ustar\0";
+        if (!posix && magic !== "ustar ")
+            throw new Refusal("not_archive", "not a ustar archive (no ustar magic)");
+        const type = String.fromCharCode(h[156]);
+        const headerSize = octal(h, 124, 12, "size");
+        if (type === "x" || type === "g" || type === "L" || type === "K") {
+            if (headerSize > META_MAX_BYTES)
+                throw new Refusal("not_archive", `an extended header of ${headerSize} bytes is past the ${META_MAX_BYTES}-byte bound`);
+            this.body = { remaining: headerSize, pad: padOf(headerSize), sink: "meta", meta: [], metaKind: type };
+            return;
+        }
+        const size = this.pax.size ?? headerSize;
+        const rawName = this.pax.path ?? this.longName ?? joinUstarName(posix ? cstr(h, 345, 155) : "", cstr(h, 0, 100));
+        const rawLink = this.pax.linkpath ?? this.longLink ?? cstr(h, 157, 100);
+        const unsupported = this.unsupportedPax;
+        this.pax = {};
+        this.unsupportedPax = undefined;
+        this.longName = undefined;
+        this.longLink = undefined;
+        const entryType = type === "0" || type === "\0" ? "file" : type === "5" ? "dir" : type === "2" ? "symlink" : undefined;
+        const name = decodeName(rawName);
+        if (entryType === undefined)
+            throw new Refusal("entry_type", `'${name}' is a ${tarTypeWord(type)} — a project bundle holds regular files, directories and symbolic links only`, name);
+        if (unsupported !== undefined) {
+            throw new Refusal("entry_type", `'${name}' carries the pax extension '${printable(unsupported)}' — a project bundle holds plain regular files, directories and symbolic links only (a sparse map, a volume offset or an unknown extension changes how the entry reads)`, name);
+        }
+        const p = landingOf(name);
+        if (p === "") {
+            if (entryType !== "dir")
+                throw new Refusal("unsafe_path", `an entry with an empty path is not a ${entryType}`, name);
+            this.body = { remaining: size, pad: padOf(size), sink: "skip" };
+            return;
+        }
+        const slash = p.indexOf("/");
+        if (PROJECT_BUNDLE_RESERVED_TOP_LEVEL.includes(slash === -1 ? p : p.slice(0, slash)))
+            throw new Refusal("reserved_path", `'${p}' is under a reserved top-level name (${PROJECT_BUNDLE_RESERVED_TOP_LEVEL.join(", ")})`, p);
+        let linkname = "";
+        if (entryType === "symlink") {
+            linkname = decodeName(rawLink);
+            if (linkname === "" || linkname.startsWith("/") || /[\x00-\x1f\x7f]/.test(linkname) || Buffer.byteLength(linkname) > PATH_MAX_BYTES) {
+                throw new Refusal("unsafe_path", `the symbolic link '${p}' needs a non-empty relative target of at most ${PATH_MAX_BYTES} bytes without control characters`, p);
+            }
+        }
+        this.tree.place(p, entryType, linkname);
+        this.entries++;
+        const entry = { path: p, type: entryType, mode: octal(h, 100, 8, "mode"), mtime: octalOrZero(h, 136, 12), size: entryType === "file" ? size : 0, linkname };
+        if (this.writer !== undefined)
+            await this.writer.entry(entry);
+        this.body = { remaining: size, pad: padOf(size), sink: entryType === "file" && this.writer !== undefined ? "write" : "skip" };
+    }
+    applyMeta(kind, data) {
+        if (kind === "L")
+            return void (this.longName = data.toString("latin1").replace(/\0+$/, ""));
+        if (kind === "K")
+            return void (this.longLink = data.toString("latin1").replace(/\0+$/, ""));
+        const records = parsePax(data);
+        for (const key of records.keys()) {
+            if (paxKeyReading(key) !== "unsupported")
+                continue;
+            if (kind === "g")
+                throw new Refusal("entry_type", `a global pax header carries the extension '${printable(key)}' — a project bundle holds plain regular files, directories and symbolic links only`);
+            this.unsupportedPax ??= key;
+        }
+        if (kind === "g") {
+            if (records.has("path") || records.has("linkpath") || records.has("size"))
+                throw new Refusal("not_archive", "a global pax header sets path / linkpath / size");
+            return;
+        }
+        const sizeText = records.get("size");
+        if (sizeText !== undefined && !/^\d{1,12}$/.test(sizeText))
+            throw new Refusal("not_archive", "a pax size record is not a decimal byte count");
+        this.pax = {
+            ...(records.has("path") ? { path: records.get("path") } : {}),
+            ...(records.has("linkpath") ? { linkpath: records.get("linkpath") } : {}),
+            ...(sizeText !== undefined ? { size: Number(sizeText) } : {}),
+        };
+    }
+}
+function padOf(size) {
+    return (BLOCK - (size % BLOCK)) % BLOCK;
+}
+function checksumHolds(h) {
+    const stored = octalOrNaN(h, 148, 8);
+    let unsigned = 0;
+    let signed = 0;
+    for (let i = 0; i < BLOCK; i++) {
+        const b = i >= 148 && i < 156 ? 0x20 : h[i];
+        unsigned += b;
+        signed += b > 127 ? b - 256 : b;
+    }
+    return stored === unsigned || stored === signed;
+}
+function octalOrNaN(h, off, len) {
+    const s = h.toString("latin1", off, off + len).replace(/[\0 ]+$/, "").replace(/^ +/, "");
+    return /^[0-7]+$/.test(s) ? parseInt(s, 8) : Number.NaN;
+}
+function octal(h, off, len, field) {
+    if (h[off] & 0x80)
+        throw new Refusal("not_archive", `the ${field} field is in base-256 form`);
+    const s = h.toString("latin1", off, off + len).replace(/[\0 ]+$/, "").replace(/^ +/, "");
+    if (s === "")
+        return 0;
+    if (!/^[0-7]+$/.test(s))
+        throw new Refusal("not_archive", `the ${field} field is not octal`);
+    return parseInt(s, 8);
+}
+function octalOrZero(h, off, len) {
+    const v = octalOrNaN(h, off, len);
+    return Number.isFinite(v) && v >= 0 ? v : 0;
+}
+function cstr(h, off, len) {
+    const end = h.indexOf(0, off);
+    return h.toString("latin1", off, end === -1 || end > off + len ? off + len : end);
+}
+function joinUstarName(prefix, name) {
+    return prefix === "" ? name : `${prefix}/${name}`;
+}
+function decodeName(raw) {
+    try {
+        return UTF8.decode(Buffer.from(raw, "latin1"));
+    }
+    catch {
+        throw new Refusal("unsafe_path", "an entry path is not valid UTF-8", raw.replace(/[^\x20-\x7e]/g, "?"));
+    }
+}
+function parsePax(data) {
+    const out = new Map();
+    let off = 0;
+    while (off < data.length) {
+        const sp = data.indexOf(0x20, off);
+        if (sp === -1)
+            throw new Refusal("not_archive", "a pax record has no length");
+        const lenText = data.toString("latin1", off, sp);
+        if (!/^\d{1,7}$/.test(lenText))
+            throw new Refusal("not_archive", "a pax record length is not decimal");
+        const len = Number(lenText);
+        if (len <= sp - off + 1 || off + len > data.length || data[off + len - 1] !== 0x0a)
+            throw new Refusal("not_archive", "a pax record is malformed");
+        const rec = data.toString("latin1", sp + 1, off + len - 1);
+        const eq = rec.indexOf("=");
+        if (eq <= 0)
+            throw new Refusal("not_archive", "a pax record has no key");
+        out.set(rec.slice(0, eq), rec.slice(eq + 1));
+        off += len;
+    }
+    return out;
+}
+function tarTypeWord(type) {
+    switch (type) {
+        case "1":
+            return "hard link";
+        case "3":
+            return "character device";
+        case "4":
+            return "block device";
+        case "6":
+            return "FIFO";
+        case "7":
+            return "contiguous file";
+        case "S":
+            return "sparse file";
+        default:
+            return `tar entry of type '${type.replace(/[^\x20-\x7e]/g, "?")}'`;
+    }
+}
+function landingOf(name) {
+    if (/[\x00-\x1f\x7f]/.test(name))
+        throw new Refusal("unsafe_path", `an entry path carries a control character`, name.replace(/[\x00-\x1f\x7f]/g, "?"));
+    if (name.startsWith("/"))
+        throw new Refusal("unsafe_path", `'${name}' is an absolute path`, name);
+    const segs = [];
+    for (const seg of name.split("/")) {
+        if (seg === "" || seg === ".")
+            continue;
+        if (seg === "..")
+            throw new Refusal("unsafe_path", `'${name}' has a '..' segment`, name);
+        segs.push(seg);
+    }
+    const p = segs.join("/");
+    if (Buffer.byteLength(p) > PATH_MAX_BYTES)
+        throw tooLong(p);
+    const wide = segs.find((seg) => Buffer.byteLength(seg) > NAME_MAX_BYTES);
+    if (wide !== undefined)
+        throw new Refusal("unsafe_path", `'${p}' has a name of ${Buffer.byteLength(wide)} bytes — the sandbox's filesystem holds at most ${NAME_MAX_BYTES} bytes per name`, p);
+    return p;
+}
+function tooLong(p) {
+    return new Refusal("unsafe_path", `an entry path of ${Buffer.byteLength(p)} bytes (starting '${printable(p.slice(0, 64))}…') — the sandbox's filesystem holds at most ${PATH_MAX_BYTES} bytes per path`);
+}
+function printable(s) {
+    return s.replace(/[^\x20-\x7e]/g, "?");
+}
+function paxKeyReading(key) {
+    switch (key) {
+        case "path":
+        case "linkpath":
+        case "size":
+            return key;
+        case "mtime":
+        case "atime":
+        case "ctime":
+        case "uid":
+        case "gid":
+        case "uname":
+        case "gname":
+        case "comment":
+        case "charset":
+        case "hdrcharset":
+        case "SCHILY.fflags":
+        case "SCHILY.dev":
+        case "SCHILY.ino":
+        case "SCHILY.nlink":
+        case "LIBARCHIVE.creationtime":
+        case "LIBARCHIVE.symlinktype":
+            return "metadata";
+        default:
+            return PAX_METADATA_FAMILIES.some((family) => key.startsWith(family)) ? "metadata" : "unsupported";
+    }
+}
+const PAX_METADATA_FAMILIES = ["SCHILY.xattr.", "LIBARCHIVE.xattr.", "SCHILY.acl.", "security.", "RHT.security."];
+class BundleTree {
+    maxObjects;
+    root = { path: "", parent: undefined, kind: "dir", children: new Map(), linkname: "", firstUnder: "" };
+    byPath = new Map();
+    links = [];
+    objects = 0;
+    offense;
+    steps = 0;
+    constructor(maxObjects) {
+        this.maxObjects = maxObjects;
+    }
+    place(p, type, linkname) {
+        const cut = p.lastIndexOf("/");
+        const parent = cut === -1 ? this.root : this.dirAt(p.slice(0, cut), p);
+        if (parent === undefined)
+            return;
+        if (parent.kind === "file" || parent.kind === "symlink")
+            return this.offend(p, parent);
+        const name = cut === -1 ? p : p.slice(cut + 1);
+        const known = parent.children.get(name);
+        if (known === undefined) {
+            this.add(parent, name, p, type, linkname, p);
+            return;
+        }
+        if (known.kind !== "implied")
+            throw new Refusal("duplicate_path", `'${p}' appears twice`, p);
+        known.kind = type;
+        known.linkname = linkname;
+        if (type === "symlink")
+            this.links.push(known);
+        if (type !== "dir")
+            this.offend(known.firstUnder, known);
+    }
+    dirAt(dirPath, entryPath) {
+        const known = this.byPath.get(dirPath);
+        if (known !== undefined)
+            return known;
+        const ends = [];
+        let base = this.root;
+        for (let end = dirPath.length;;) {
+            ends.push(end);
+            const up = dirPath.lastIndexOf("/", end - 1);
+            if (up === -1)
+                break;
+            const found = this.byPath.get(dirPath.slice(0, up));
+            if (found !== undefined) {
+                base = found;
+                break;
+            }
+            end = up;
+        }
+        let cur = base;
+        for (let k = ends.length - 1; k >= 0; k--) {
+            if (cur.kind === "file" || cur.kind === "symlink") {
+                this.offend(entryPath, cur);
+                return undefined;
+            }
+            const end = ends[k];
+            cur = this.add(cur, dirPath.slice(dirPath.lastIndexOf("/", end - 1) + 1, end), dirPath.slice(0, end), "implied", "", entryPath);
+        }
+        return cur;
+    }
+    add(parent, name, p, kind, linkname, firstUnder) {
+        if (this.objects >= this.maxObjects)
+            throw new Refusal("too_many_entries", `the bundle unpacks to more than ${this.maxObjects} filesystem objects (its entries and the directories their paths imply)`);
+        this.objects++;
+        const node = { path: p, parent, kind, children: new Map(), linkname, firstUnder };
+        parent.children.set(name, node);
+        this.byPath.set(p, node);
+        if (kind === "symlink")
+            this.links.push(node);
+        return node;
+    }
+    offend(entryPath, blocker) {
+        this.offense ??= { entryPath, blocker };
+    }
+    topLevel() {
+        return [...this.root.children.keys()].sort();
+    }
+    async judge() {
+        for (const link of this.links) {
+            this.landingOf(link, 0);
+            if (this.steps >= YIELD_STEPS) {
+                this.steps = 0;
+                await new Promise((resolve) => setImmediate(resolve));
+            }
+        }
+        if (this.offense !== undefined)
+            throw this.offenseRefusal(this.offense);
+    }
+    offenseRefusal({ entryPath, blocker }) {
+        if (blocker.kind === "file")
+            return new Refusal("unsafe_path", `'${entryPath}' is under the regular file '${blocker.path}'`, entryPath);
+        const end = this.walk(this.landingOf(blocker, 0), entryPath.slice(blocker.path.length + 1), 0, blocker);
+        const top = end.node === this.root && end.depth > 0 ? end.top : undefined;
+        if (top !== undefined && PROJECT_BUNDLE_RESERVED_TOP_LEVEL.includes(top)) {
+            return new Refusal("reserved_path", `'${entryPath}' lands under '${top}' through the symbolic link '${blocker.path}' of the bundle — a reserved top-level name`, entryPath);
+        }
+        return new Refusal("unsafe_path", `'${entryPath}' is written through a symbolic link of the bundle ('${blocker.path}')`, entryPath);
+    }
+    landingOf(link, hops) {
+        if (link.landing !== undefined)
+            return link.landing;
+        if (hops >= MAX_LINK_HOPS)
+            throw new Refusal("unsafe_path", `the symbolic link '${link.path}' -> '${link.linkname}' does not land within ${MAX_LINK_HOPS} links (the bundle's links form a loop, or a chain that deep)`, link.path);
+        const at = this.walk({ node: link.parent, depth: 0, top: undefined }, link.linkname, hops + 1, link);
+        link.landing = at;
+        return at;
+    }
+    walk(from, text, hops, owner) {
+        let { node, depth, top } = from;
+        for (let i = 0; i <= text.length;) {
+            let j = text.indexOf("/", i);
+            if (j === -1)
+                j = text.length;
+            const seg = text.slice(i, j);
+            i = j + 1;
+            this.steps++;
+            if (seg === "" || seg === ".")
+                continue;
+            if (seg === "..") {
+                if (depth > 0) {
+                    depth--;
+                    if (depth === 0)
+                        top = undefined;
+                    continue;
+                }
+                if (node.parent === undefined)
+                    throw new Refusal("unsafe_path", `the symbolic link '${owner.path}' -> '${owner.linkname}' does not stay inside the bundle (resolved through the bundle's own links)`, owner.path);
+                node = node.parent;
+                continue;
+            }
+            if (depth > 0) {
+                depth++;
+                continue;
+            }
+            const child = node.children.get(seg);
+            if (child === undefined) {
+                if (node === this.root)
+                    top = seg;
+                depth = 1;
+                continue;
+            }
+            if (child.kind === "symlink") {
+                ({ node, depth, top } = this.landingOf(child, hops));
+                continue;
+            }
+            node = child;
+        }
+        return { node, depth, top };
+    }
+}
+function createCanonicalWriter() {
+    const gz = createGzip();
+    const out = [];
+    gz.on("data", (b) => out.push(b));
+    let pending = 0;
+    const write = async (b) => {
+        if (!gz.write(b))
+            await once(gz, "drain");
+    };
+    return {
+        async entry(e) {
+            const name = e.type === "dir" ? `${e.path}/` : e.path;
+            const needsPax = Buffer.byteLength(name) > 100 || Buffer.byteLength(e.linkname) > 100;
+            if (needsPax) {
+                const recs = Buffer.from(paxRecord("path", name) + (Buffer.byteLength(e.linkname) > 100 ? paxRecord("linkpath", e.linkname) : ""), "utf8");
+                await write(ustarHeader({ name: "PaxHeader", type: "x", mode: 0o644, size: recs.length, mtime: e.mtime, linkname: "" }));
+                await write(recs);
+                await write(Buffer.alloc(padOf(recs.length)));
+            }
+            const mode = e.type === "file" ? (e.mode & 0o111 ? 0o755 : 0o644) : e.type === "dir" ? 0o755 : 0o777;
+            const type = e.type === "file" ? "0" : e.type === "dir" ? "5" : "2";
+            await write(ustarHeader({ name: needsPax ? truncateUtf8(name, 100) : name, type, mode, size: e.size, mtime: e.mtime, linkname: needsPax ? truncateUtf8(e.linkname, 100) : e.linkname }));
+            pending = e.size;
+        },
+        async content(part) {
+            await write(part);
+        },
+        async endContent() {
+            await write(Buffer.alloc(padOf(pending)));
+            pending = 0;
+        },
+        async end() {
+            await write(Buffer.alloc(BLOCK * 2));
+            gz.end();
+            await once(gz, "end");
+            return new Uint8Array(Buffer.concat(out));
+        },
+        abort() {
+            gz.destroy();
+        },
+    };
+}
+function paxRecord(key, value) {
+    const body = ` ${key}=${value}\n`;
+    let len = Buffer.byteLength(body) + 1;
+    while (String(len).length + Buffer.byteLength(body) !== len)
+        len = String(len).length + Buffer.byteLength(body);
+    return `${len}${body}`;
+}
+function truncateUtf8(s, max) {
+    let b = Buffer.from(s, "utf8");
+    if (b.length <= max)
+        return s;
+    b = b.subarray(0, max);
+    return b.toString("utf8").replace(/�+$/, "");
+}
+function ustarHeader(f) {
+    const h = Buffer.alloc(BLOCK, 0);
+    Buffer.from(f.name, "utf8").copy(h, 0, 0, 100);
+    h.write(octalField(f.mode, 8), 100, "latin1");
+    h.write(octalField(0, 8), 108, "latin1");
+    h.write(octalField(0, 8), 116, "latin1");
+    h.write(octalField(f.size, 12), 124, "latin1");
+    h.write(octalField(Math.min(f.mtime, 0o77777777777), 12), 136, "latin1");
+    h.write("        ", 148, "latin1");
+    h.write(f.type, 156, "latin1");
+    Buffer.from(f.linkname, "utf8").copy(h, 157, 0, 100);
+    h.write("ustar\0", 257, "latin1");
+    h.write("00", 263, "latin1");
+    h.write(octalField(0, 8), 329, "latin1");
+    h.write(octalField(0, 8), 337, "latin1");
+    let sum = 0;
+    for (let i = 0; i < BLOCK; i++)
+        sum += h[i];
+    h.write(`${sum.toString(8).padStart(6, "0")}\0 `, 148, "latin1");
+    return h;
+}
+function octalField(n, width) {
+    return `${Math.max(0, Math.floor(n)).toString(8).padStart(width - 1, "0")}\0`;
+}
+//# sourceMappingURL=project-bundle.js.map

package/dist/run-cancel-context.d.ts

@@ -1,3 +1,20 @@
+/**
+ * [ref] 件3(cli [ref] sema-bug4 (d) / server [ref]):**取消现场快照**的唯一铸点。
+ *
+ * 语义边界、缺席纪律、「为什么不写模型调用相位」全部成文在类型属主处 —— 见
+ * `plugins/store-contracts.ts` 的 `RunCancelContext` 顶注。本文件只做装配。
+ *
+ * 三条用户取消腿共用它(**判别材料只许有一份口径**):
+ *  · `POST /v1/runs/:id/cancel` 的 park 取消腿(`http/routes/runs.ts` cancelSuspended);
+ *  · `/v1/tasks/stream` 的客户端断连腿(`http/routes/tasks.ts`,没读到 done 的那一支);
+ *  · durable bg 腿的 abort 结算(`runs.ts` —— 同一条 cancel 动词打到 running 行上时的终局形)。
+ *
+ * [ref] 起,「取消终局整只长什么样」也收在本文件({@link mintCancelledResult})—— 快照与它所在的
+ * 那条结果由同一个属主铸,三条腿一份口径。
+ *
+ * [ref] 起,「这次取消是谁发起的」也收在本文件:中止那一刻经 {@link createRunAbort} 的句柄登记成因,终局铸点从同一只句柄读。
+ */
+import type { TerminalCause } from "@sema-agent/core";
 import type { AbortCause, PersistedTaskResult, RunCancelContext } from "./plugins/store-contracts.js";
 /**
  * @param taskId  这条 run 的账本 id(turn 活性登记的键)。
@@ -58,6 +75,23 @@ export declare function mintCancelledResult<R extends PersistedTaskResult>(args:
 export declare function mintCancelledResult(args: CancelMintArgs & {
     engineResult?: undefined;
 }): PersistedTaskResult;
+/**
+ * 被取消的续跑腿、且这张卡被本服务 expire 之后,终局上的那句话 —— **全仓单源**([ref])。
+ *
+ * 引擎对一条「批过的那一步没开跑就结束」的续跑腿,在终局文案上补一句通用的话:「…the checkpoint was REOPENED (pending): the same approval can be resumed again」
+ * (它对想再续的宿主是真话:引擎确实把卡放回了 pending)。而本服务按取消语义结算这张卡(取消 = run 死:绝不重新 park,卡 expire),于是写在终局上的那句话与可操作面
+ * 不一致 —— 文案说可再续,待办队列里没有这张卡、同一张卡再决断 404。取消不可逆(契约),所以真话是这一句。
+ * 引擎那句里「放回 pending」的事实与「同一批准可再续」的结论都是**引擎当时**的,本服务在其后改了卡的状态,最后一个写手的句子才对。
+ */
+export declare const CARD_SETTLED_BY_CANCEL_MESSAGE = "Cancelled \u2014 the approved action never started, and the cancel settled this approval: it cannot be resumed (start a new run to continue)";
+/**
+ * 一条被取消的续跑腿的失败终局,在本服务亲手 expire 了它那张卡之后的形:**只换文案**,码(引擎补的 `resume.reopened_unstarted` 等)、成因位、统计与其余字段原样
+ * (码立住是成文契约;换码是另一条 wire 变更)。非 `failed` 终局原样返回。纯函数,不改入参。
+ * 调用点只有 `http/resume-legs.ts` 的 `reopenedAfterLeg`(判据 = 店的事实「本座 expire 了一张 pending 的卡」,不嗅引擎文案)。
+ */
+export declare function withCardSettledByCancelMessage<R extends {
+    terminal: TerminalCause;
+}>(leg: R): R;
 /** {@link mintCancelledResult} 的公共实参(`engineResult` 另列:在场与否决定返回型)。 */
 interface CancelMintArgs {
     /** 这条 run 的账本 id(活性登记的键;账本不在场时给空串,快照按「证不出」处理)。 */

package/dist/run-cancel-context.js

@@ -36,6 +36,13 @@ export function mintCancelledResult(args) {
         abortCause: args.cause,
     };
 }
+export const CARD_SETTLED_BY_CANCEL_MESSAGE = "Cancelled — the approved action never started, and the cancel settled this approval: it cannot be resumed (start a new run to continue)";
+export function withCardSettledByCancelMessage(leg) {
+    const t = leg.terminal;
+    if (t.kind !== "failed")
+        return leg;
+    return { ...leg, terminal: { ...t, message: CARD_SETTLED_BY_CANCEL_MESSAGE } };
+}
 export function buildCancelledLedgerRow(c) {
     const t = c.terminal;
     return {

package/dist/run-local.js

@@ -770,14 +770,8 @@ export async function runLocal(argv, deps = {}) {
     }
     if (result.terminal.kind !== "completed" || unfinishedStop !== undefined)
         exitCode = 1;
-    if (memorySync) {
-        try {
-            await memorySync.syncOnce("post-task");
-        }
-        catch (err) {
-            logger.warn("memory_sync_failed", { reason: "post-task", err: String(err) });
-        }
-    }
+    if (memorySync)
+        await memorySync.syncOnce("post-task");
     await settleSessionBackground();
     runner.sessions.dispose();
     subRunner.sessions.dispose();