@jitsusama/agentic-harness.core 0.6.2 → 0.6.4

package/dist/internal/quest/bash-write.js

@@ -6,8 +6,10 @@
  * does not trip the gate. This is a nudge toward the right stage,
  * not a security boundary.
  */
+import { isAbsolute, join, resolve } from "node:path";
 import { tokenize } from "../../command/index.js";
 import { stripHeredocBodies, stripShellData, unquote, } from "../../shell/index.js";
+import { createdBy, removedBy, unwrap } from "./bash-effects.js";
 /** Git subcommands that change repository or working-tree state. */
 const GIT_MUTATING = /\bgit(?:\s+(?:-c\s+\S+|-C\s+\S+|--git-dir=\S+|--work-tree=\S+|--no-pager))*\s+(add|commit|push|pull|merge|rebase|reset|checkout|stash|cherry-pick|revert|tag|switch|restore|am|format-patch)\b/i;
 /** Shell patterns that write to the filesystem via redirection or in-place edit. */
@@ -69,6 +71,24 @@ export function bashWriteTargets(command) {
             return;
         targets.push(value);
     };
+    for (const target of patternTargets(skeleton))
+        add(target);
+    for (const simple of tokenize(command).commands) {
+        for (const target of commandTargets(simple))
+            add(target);
+    }
+    return [...new Set(targets)];
+}
+/**
+ * Write destinations found by pattern in a data-stripped skeleton, for
+ * the grammar the command model declines, such as a loop or a subshell.
+ */
+function patternTargets(skeleton) {
+    const found = [];
+    const add = (token) => {
+        if (token)
+            found.push(token);
+    };
     // Redirect destinations: the token following > or >>. A leading
     // digit or & marks an fd redirect (2>, &>), which routes a stream
     // rather than naming a content target, so it is skipped.
@@ -96,55 +116,309 @@ export function bashWriteTargets(command) {
             add(token);
         }
     }
-    for (const target of modelledTargets(command))
-        add(target);
-    return [...new Set(targets)];
+    return found;
 }
 /**
- * Write destinations read from the command model, where quoting is
- * already understood.
+ * Resolve where a bash command writes, in the directory each writing
+ * command actually runs in.
  *
- * Three shapes, the same three the patterns above look for: a redirect's
- * target, `tee`'s file arguments, and the file arguments of an in-place
- * editor. A file-descriptor redirect (`2>`, `&>`) is skipped, matching
- * what the pattern pass does, since it routes a stream rather than naming
- * a content target.
+ * The session directory is only where the command starts: `cd <tree> &&
+ * cat >> x_test.go` writes inside the tree, and reading it against the
+ * session directory is how a write in a tracked tree came to be judged as
+ * one in the repository the session happened to open. So the command
+ * model is walked in order, each `cd` moving the directory for what
+ * follows, with the command's own variables filled in.
  *
- * An editor's script is reported alongside its file, because telling one
- * from the other means knowing whether this `sed` is the BSD or the GNU
- * one. A script cannot name tracked code, so including it costs nothing,
- * whereas missing the file was the whole defect.
+ * A target whose location the command does not say is reported as
+ * unresolved rather than guessed: a `cd` into a command substitution, a
+ * variable from outside the command, or a relative target in a subshell
+ * or loop that changes directory. A guess judges a file nobody wrote,
+ * while an unresolved target can still be checked on disk afterwards.
+ *
+ * What a command removes is placed the same way and kept apart, since
+ * removing a document is a different question from writing one. It is
+ * only read where the command model applies; a removal inside a loop or
+ * a subshell is left to the check on disk.
  */
-function modelledTargets(command) {
+export function resolveBashWrites(command, place) {
+    const skeleton = stripShellData(stripHeredocBodies(command));
+    const known = assignmentsIn(skeleton, command);
+    const paths = [];
+    const removed = [];
+    const unresolved = [];
+    const locate = (raw, dir, into = paths) => {
+        const bare = raw.replace(/^['"]/, "").replace(/['"]$/, "");
+        if (!bare)
+            return;
+        const value = expand(bare, known);
+        const absolute = value === undefined ? undefined : absoluteIn(value, dir, place.home);
+        if (absolute === undefined)
+            unresolved.push(value ?? bare);
+        else
+            into.push(absolute);
+    };
     const line = tokenize(command);
-    const found = [];
-    for (const simple of line.commands) {
-        for (const redirect of simple.redirects) {
-            if (!redirect.target)
+    if (line.supported) {
+        let dir = place.cwd;
+        for (const simple of line.commands) {
+            const argv = argvOf(simple);
+            if (argv[0] === "cd") {
+                dir = changeDirectory(dir, argv[1], known, place.home);
                 continue;
-            if (/^[0-9&]/.test(redirect.operator))
-                continue;
-            found.push(unquote(redirect.target.text));
+            }
+            for (const target of commandTargets(simple))
+                locate(target, dir);
+            for (const target of removedBy(unwrap(argv))) {
+                locate(target, dir, removed);
+            }
         }
-        const argv = simple.argv.map((word) => unquote(word.text));
-        const name = argv[0];
-        if (!name)
-            continue;
-        const rest = argv.slice(1).filter((token) => !token.startsWith("-"));
-        if (name === "tee")
-            found.push(...rest);
-        if (/^(g?sed|perl)$/.test(name) && editsInPlace(simple.argv)) {
-            found.push(...rest);
+    }
+    else {
+        // Outside the grammar there is no order to follow, so a relative
+        // target is only placed when nothing in the command changes directory.
+        const moves = /(?:^|[\s;&|(])cd(?:\s|$)/.test(skeleton);
+        for (const target of patternTargets(skeleton)) {
+            locate(target, moves ? undefined : place.cwd);
         }
     }
+    return {
+        paths: [...new Set(paths)],
+        removed: [...new Set(removed)],
+        unresolved: [...new Set(unresolved)],
+    };
+}
+/**
+ * The directory after `cd <target>`, or undefined once it is no longer
+ * knowable: `cd -`, or a target the command's own variables cannot fill.
+ */
+function changeDirectory(dir, target, known, home) {
+    if (target === undefined)
+        return home;
+    if (target === "-")
+        return undefined;
+    const value = expand(target, known);
+    return value === undefined ? undefined : absoluteIn(value, dir, home);
+}
+/** A path made absolute, or undefined when it is relative to nothing known. */
+function absoluteIn(path, dir, home) {
+    if (path === "~")
+        return home;
+    if (path.startsWith("~/"))
+        return join(home, path.slice(2));
+    if (isAbsolute(path))
+        return resolve(path);
+    return dir === undefined ? undefined : resolve(dir, path);
+}
+/**
+ * One command's write destinations, read from the command model, where
+ * quoting is already understood.
+ *
+ * The three shapes `patternTargets` also looks for, a redirect's target,
+ * `tee`'s file arguments and the file arguments of an in-place editor,
+ * plus what a command creates without a redirect (see `createdBy`), read
+ * through wrappers such as `nohup` and `env`. A file-descriptor redirect
+ * (`2>`, `&>`) is skipped, matching what the pattern pass does, since it
+ * routes a stream rather than naming a content target.
+ *
+ * An editor's script is told apart from its files by reading its options
+ * the way the editor does, since a script reported as a file is a path
+ * nobody wrote, and one that happens to look like a quest document gets
+ * a write refused that never touched it.
+ */
+function commandTargets(simple) {
+    const found = [];
+    for (const redirect of simple.redirects) {
+        if (!redirect.target)
+            continue;
+        if (/^[0-9&]/.test(redirect.operator))
+            continue;
+        found.push(unquote(redirect.target.text));
+    }
+    const argv = unwrap(argvOf(simple));
+    const name = argv[0];
+    if (!name)
+        return found;
+    found.push(...createdBy(argv));
+    if (name === "tee") {
+        found.push(...argv.slice(1).filter((token) => !token.startsWith("-")));
+    }
+    if (/^g?sed$/.test(name))
+        found.push(...sedFiles(argv.slice(1)));
+    if (name === "perl")
+        found.push(...perlFiles(argv.slice(1)));
     return found;
 }
-/** Whether an editor invocation carries the in-place flag. */
-function editsInPlace(argv) {
-    return argv.some((word) => {
-        const text = unquote(word.text);
-        return text === "-i" || text.startsWith("-i");
-    });
+/** Short sed options that take the next word as their value. */
+const SED_VALUED = new Set(["e", "f", "l"]);
+/**
+ * The files a sed invocation edits in place, or none when it does not.
+ *
+ * Both spellings of the in-place flag are read. GNU attaches its optional
+ * suffix (`-i.bak`); BSD always takes one as the next word, and that word
+ * is only read as a suffix when it looks like one (empty, or starting with
+ * a dot), since `sed -i 's/a/b/' f` is the GNU spelling written on a Mac.
+ * Without `-e` or `-f`, the first operand is the script.
+ */
+function sedFiles(args) {
+    const operands = [];
+    let inPlace = false;
+    let scripted = false;
+    for (let at = 0; at < args.length; at++) {
+        const arg = args[at] ?? "";
+        if (arg === "--") {
+            operands.push(...args.slice(at + 1));
+            break;
+        }
+        if (arg.startsWith("--")) {
+            const [option] = arg.split("=", 1);
+            if (option === "--in-place")
+                inPlace = true;
+            if (option === "--expression" || option === "--file") {
+                scripted = true;
+                if (!arg.includes("="))
+                    at++;
+            }
+            continue;
+        }
+        if (!arg.startsWith("-") || arg === "-") {
+            operands.push(arg);
+            continue;
+        }
+        for (let char = 1; char < arg.length; char++) {
+            const flag = arg[char] ?? "";
+            if (flag === "i") {
+                inPlace = true;
+                const next = args[at + 1];
+                const bare = char === arg.length - 1;
+                if (bare && next !== undefined && /^(\.|$)/.test(next))
+                    at++;
+                break;
+            }
+            if (SED_VALUED.has(flag)) {
+                if (flag !== "l")
+                    scripted = true;
+                if (char === arg.length - 1)
+                    at++;
+                break;
+            }
+        }
+    }
+    if (!inPlace)
+        return [];
+    return scripted ? operands : operands.slice(1);
+}
+/** Perl switches whose value is the rest of the word, or the next word. */
+const PERL_VALUED = new Set(["e", "E", "I", "M", "m", "x"]);
+/** Perl switches whose optional value can only be attached. */
+const PERL_ATTACHED = new Set(["i", "l", "0", "C", "d", "D", "F"]);
+/**
+ * The files a perl invocation edits in place, or none when it does not.
+ *
+ * Switches cluster (`-pi`, `-ne`), so each word is read one switch at a
+ * time. Without `-e` or `-E`, the first operand is the program file.
+ */
+function perlFiles(args) {
+    const operands = [];
+    let inPlace = false;
+    let inline = false;
+    for (let at = 0; at < args.length; at++) {
+        const arg = args[at] ?? "";
+        if (arg === "--") {
+            operands.push(...args.slice(at + 1));
+            break;
+        }
+        if (!arg.startsWith("-") || arg === "-") {
+            operands.push(...args.slice(at));
+            break;
+        }
+        for (let char = 1; char < arg.length; char++) {
+            const flag = arg[char] ?? "";
+            if (flag === "i")
+                inPlace = true;
+            if (PERL_VALUED.has(flag)) {
+                if (flag === "e" || flag === "E")
+                    inline = true;
+                if (char === arg.length - 1)
+                    at++;
+                break;
+            }
+            if (PERL_ATTACHED.has(flag))
+                break;
+        }
+    }
+    if (!inPlace)
+        return [];
+    return inline ? operands : operands.slice(1);
+}
+/** A command's arguments as the command receives them: braces expanded, quotes removed. */
+function argvOf(simple) {
+    return simple.argv.flatMap((word) => expandBraces(word.text).map(unquote));
+}
+/**
+ * A word with its brace lists expanded, the way bash does before a
+ * command sees its arguments: `lab/{a,b}` is `lab/a lab/b`.
+ *
+ * Only an unquoted list with a comma at its top level expands, so
+ * `'{a,b}'`, `{solo}` and a variable's `${NAME}` stay as written. A
+ * sequence such as `{1..3}` is left alone too; nothing that writes into a
+ * quest folder has been seen to use one.
+ */
+function expandBraces(word) {
+    for (let open = 0; open < word.length; open = skipQuoted(word, open) + 1) {
+        if (word[open] !== "{" || word[open - 1] === "$")
+            continue;
+        const list = braceList(word, open);
+        if (!list)
+            continue;
+        const prefix = word.slice(0, open);
+        const suffix = word.slice(list.close + 1);
+        return list.parts.flatMap((part) => expandBraces(prefix + part + suffix));
+    }
+    return [word];
+}
+/**
+ * The alternatives of the brace list opening at `open`, and where it
+ * closes, or undefined when the braces hold no top-level comma or never
+ * close.
+ */
+function braceList(word, open) {
+    const parts = [];
+    let depth = 0;
+    let start = open + 1;
+    for (let at = open; at < word.length; at = skipQuoted(word, at) + 1) {
+        const char = word[at];
+        if (char === "{")
+            depth++;
+        else if (char === "}" && --depth === 0) {
+            if (parts.length === 0)
+                return undefined;
+            parts.push(word.slice(start, at));
+            return { parts, close: at };
+        }
+        else if (char === "," && depth === 1) {
+            parts.push(word.slice(start, at));
+            start = at + 1;
+        }
+    }
+    return undefined;
+}
+/**
+ * The last index of the quoted span or escape starting at `at`, or `at`
+ * itself when nothing starts there, so a scan can step past quoted text.
+ */
+function skipQuoted(word, at) {
+    const char = word[at];
+    if (char === "\\")
+        return at + 1;
+    if (char !== "'" && char !== '"')
+        return at;
+    let end = at + 1;
+    while (end < word.length && word[end] !== char) {
+        if (char === '"' && word[end] === "\\")
+            end++;
+        end++;
+    }
+    return end;
 }
 /**
  * The variables a command assigns to itself, last assignment winning.

package/dist/internal/quest/io.js

@@ -26,7 +26,7 @@
  * that bypasses it can still write through. We rely on
  * every README write going through `withQuestLock`.
  */
-import { closeSync, existsSync, fsyncSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeSync, } from "node:fs";
+import { closeSync, existsSync, fstatSync, fsyncSync, linkSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeSync, } from "node:fs";
 import { dirname, join } from "node:path";
 /** Lock-acquire retry budget per call. */
 const LOCK_TIMEOUT_MS = 5000;
@@ -102,30 +102,52 @@ function isProcessAlive(pid) {
         return err.code === "EPERM";
     }
 }
+/**
+ * Take the lock over if its holder has gone or it is too old to be a
+ * write in progress.
+ *
+ * A lock with no readable record is judged by its file's age alone: a
+ * holder creates the lock and then writes its record, so for a moment
+ * every live lock is empty, and treating that as abandoned took locks
+ * from their holders. Taking over moves the lock aside and checks the
+ * move took the one judged stale; deleting by name could delete a lock
+ * another writer made after taking over first.
+ */
 function tryStealStaleLock(lockPath, now) {
-    const record = readLockRecord(lockPath);
-    if (!record) {
-        // Malformed lock file; remove and retry.
-        try {
-            unlinkSync(lockPath);
-        }
-        catch {
-            // Another process beat us to the cleanup; that's fine.
-        }
+    let judged;
+    try {
+        judged = statSync(lockPath);
+    }
+    catch {
+        // Released since the failed create; the next attempt takes it.
         return true;
     }
-    const age = now - record.startedAt;
-    if (age < STALE_LOCK_MS && isProcessAlive(record.pid))
+    const record = readLockRecord(lockPath);
+    const stale = record
+        ? now - record.startedAt >= STALE_LOCK_MS || !isProcessAlive(record.pid)
+        : now - judged.mtimeMs >= STALE_LOCK_MS;
+    if (!stale)
         return false;
+    const aside = `${lockPath}.stale-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
     try {
-        unlinkSync(lockPath);
-        return true;
+        renameSync(lockPath, aside);
     }
     catch {
-        // Another process beat us to the cleanup; let the
-        // next loop iteration retry the acquire.
+        // Somebody else took it over first; the next attempt sees theirs.
         return false;
     }
+    if (statSync(aside).ino !== judged.ino) {
+        // Moved a fresh lock another writer made after taking over first.
+        // Put it back, unless a third already made one, which then stands.
+        try {
+            linkSync(aside, lockPath);
+        }
+        catch {
+            // EEXIST: the newer lock stands, as above.
+        }
+    }
+    unlinkSync(aside);
+    return true;
 }
 function acquireLock(lockPath) {
     const deadline = Date.now() + LOCK_TIMEOUT_MS;
@@ -139,7 +161,7 @@ function acquireLock(lockPath) {
             };
             writeSync(fd, JSON.stringify(payload));
             fsyncSync(fd);
-            return fd;
+            return { fd, ino: fstatSync(fd).ino };
         }
         catch (err) {
             const code = err.code;
@@ -165,15 +187,18 @@ function acquireLock(lockPath) {
         }
     }
 }
-function releaseLock(lockPath, fd) {
+function releaseLock(lockPath, held) {
     try {
-        closeSync(fd);
+        closeSync(held.fd);
     }
     catch {
         // Already closed; cleanup of the path below still runs.
     }
     try {
-        unlinkSync(lockPath);
+        // Only this holder's own lock: one taken over from it belongs to
+        // whoever made the new one.
+        if (statSync(lockPath).ino === held.ino)
+            unlinkSync(lockPath);
     }
     catch {
         // Lock file was stolen out from under us or never
@@ -203,12 +228,12 @@ export function withQuestLock(questDir, fn) {
             // Stat failed; the acquire loop handles it.
         }
     }
-    const fd = acquireLock(lockPath);
+    const held = acquireLock(lockPath);
     try {
         return fn();
     }
     finally {
-        releaseLock(lockPath, fd);
+        releaseLock(lockPath, held);
     }
 }
 /**

package/dist/internal/quest/record-audit.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The record's rules, read from disk rather than from a single write.
+ *
+ * The gate judges a write by its path before it lands, which cannot see
+ * what a command made without saying so, how big a file turned out, or
+ * whether a document cites it. The audit reads the whole quest folder
+ * afterwards and reports what the record holds that it should not: the
+ * check after each write, conclude's refusal and the migration all ask
+ * it the same question.
+ */
+import { type Stats } from "node:fs";
+import { type AttachmentFile, type AttachmentProblem } from "./record.js";
+/** What a quest folder holds that its record should not. */
+export interface RecordAudit {
+    /** Paths outside the record, each by its outermost folder or file. */
+    readonly strays: string[];
+    /** Attachments that break the limits, and how. */
+    readonly attachments: {
+        rel: string;
+        problem: AttachmentProblem;
+    }[];
+    /** Links into `attachments/` that name no attachment. */
+    readonly broken: {
+        document: string;
+        target: string;
+    }[];
+    /** Attachments no document cites, which the backup leaves out. */
+    readonly uncited: string[];
+}
+/** Read a quest folder and report what its record should not hold. */
+export declare function auditQuestRecord(questDir: string): RecordAudit;
+/**
+ * Whether a record may conclude as it is. Uncited attachments do not
+ * stop it: the backup leaves them out, which is their only cost.
+ */
+export declare function isRecordSound(audit: RecordAudit): boolean;
+/**
+ * What the attachment rules need to know about one path on disk, named
+ * by `rel` as it would sit in the record. The migration asks this of a
+ * file before it moves, so it is judged the same way the audit would
+ * judge it once it lands.
+ */
+export declare function attachmentFileAt(path: string, rel: string, stats?: Stats): AttachmentFile;

package/dist/internal/quest/record-audit.js

@@ -0,0 +1,126 @@
+/**
+ * The record's rules, read from disk rather than from a single write.
+ *
+ * The gate judges a write by its path before it lands, which cannot see
+ * what a command made without saying so, how big a file turned out, or
+ * whether a document cites it. The audit reads the whole quest folder
+ * afterwards and reports what the record holds that it should not: the
+ * check after each write, conclude's refusal and the migration all ask
+ * it the same question.
+ */
+import { closeSync, lstatSync, openSync, readdirSync, readFileSync, readSync, } from "node:fs";
+import { basename, join } from "node:path";
+import { ATTACHMENT_LIMITS, attachmentCitations, attachmentProblem, questRecordPath, } from "./record.js";
+/**
+ * Files the quest machinery and the system keep in a quest folder: the
+ * quest lock, the atomic writer's half-written files and Finder's notes.
+ */
+function isMachinery(name) {
+    return (name === ".quest.lock" ||
+        name === ".DS_Store" ||
+        /^\..+\.tmp-\d+-/.test(name));
+}
+/** Read a quest folder and report what its record should not hold. */
+export function auditQuestRecord(questDir) {
+    const questsRoot = join(questDir, "..");
+    const quest = basename(questDir);
+    const strays = [];
+    const problems = [];
+    const documents = [];
+    const attachments = [];
+    const walk = (dir) => {
+        for (const name of readdirSync(dir).sort()) {
+            if (isMachinery(name))
+                continue;
+            const path = join(dir, name);
+            const place = questRecordPath(questsRoot, path);
+            if (!place)
+                continue;
+            const stats = lstatSync(path);
+            switch (place.place) {
+                case "stray":
+                    strays.push(place.rel);
+                    break;
+                case "readme":
+                case "document":
+                    if (stats.isFile()) {
+                        documents.push({
+                            rel: place.rel,
+                            text: readFileSync(path, "utf8"),
+                        });
+                    }
+                    else
+                        strays.push(place.rel);
+                    break;
+                case "folder":
+                    if (stats.isDirectory())
+                        walk(path);
+                    else
+                        strays.push(place.rel);
+                    break;
+                case "attachment": {
+                    const problem = attachmentProblem(attachmentFileAt(path, place.rel, stats));
+                    if (problem)
+                        problems.push({ rel: place.rel, problem });
+                    else if (stats.isDirectory())
+                        walk(path);
+                    else
+                        attachments.push(place.rel);
+                    break;
+                }
+            }
+        }
+    };
+    walk(questDir);
+    const { cited, broken } = attachmentCitations(quest, documents, attachments);
+    return {
+        strays: strays.sort(),
+        attachments: problems.sort((a, b) => compare(a.rel, b.rel)),
+        broken,
+        uncited: attachments.filter((rel) => !cited.has(rel)).sort(),
+    };
+}
+/**
+ * Whether a record may conclude as it is. Uncited attachments do not
+ * stop it: the backup leaves them out, which is their only cost.
+ */
+export function isRecordSound(audit) {
+    return (audit.strays.length === 0 &&
+        audit.attachments.length === 0 &&
+        audit.broken.length === 0);
+}
+/**
+ * What the attachment rules need to know about one path on disk, named
+ * by `rel` as it would sit in the record. The migration asks this of a
+ * file before it moves, so it is judged the same way the audit would
+ * judge it once it lands.
+ */
+export function attachmentFileAt(path, rel, stats = lstatSync(path)) {
+    const kind = stats.isSymbolicLink()
+        ? "symlink"
+        : stats.isDirectory()
+            ? "directory"
+            : stats.isFile()
+                ? "file"
+                : "other";
+    return {
+        rel,
+        kind,
+        size: stats.size,
+        head: kind === "file" ? headOf(path) : new Uint8Array(),
+    };
+}
+/** A file's first bytes, as many as the text sniff reads. */
+function headOf(path) {
+    const buffer = new Uint8Array(ATTACHMENT_LIMITS.sniffBytes);
+    const fd = openSync(path, "r");
+    try {
+        return buffer.subarray(0, readSync(fd, buffer, 0, buffer.length, 0));
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function compare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}