@bastani/atomic 0.9.19-alpha.5 → 0.9.19-alpha.7

package/dist/core/tools/file-mutation-coordinator.d.ts

@@ -0,0 +1,255 @@
+import { type SnapshotStore } from "./hashline-engine/index.ts";
+/**
+ * Stable token carried inside every conflict message.
+ *
+ * It lives in the message text, not only on the class, because nothing typed survives the
+ * trip from a tool to a workflow: a subagent result reports `cause`/`error` as strings, a
+ * workflow task result has no error field at all, and a workflow runner reduces a failure to
+ * `err.message`. Matching this token is how a consumer downstream of that flattening tells a
+ * mutation conflict apart from an ordinary tool error.
+ *
+ * It is placed at the start of the message so it survives truncation of the tail as the
+ * message is relayed. Never change it without updating every consumer that matches on it.
+ */
+export declare const FILE_MUTATION_CONFLICT_CODE = "FILE_MUTATION_CONFLICT";
+/**
+ * Reasons report a {@link FileMutationLiveState} wherever the live target can be described,
+ * which is everywhere except `target_unreadable`: that one exists precisely because the target
+ * could not be read, so claiming a size or a tag for it would be invention.
+ *
+ * Only the reasons that have something to compare against also report a
+ * {@link FileMutationConflictEvidence} diff: `no_prior_observation` never read the file, and
+ * `foreign_snapshot` presented a tag naming content this session has never seen, so in both
+ * cases there is no prior side to diff.
+ */
+export type FileMutationConflictReason = 
+/** Live content moved between the mutation being prepared and the write being attempted. */
+"changed_before_write"
+/** Overwrite attempted with no prior read of this file in this session. */
+ | "no_prior_observation"
+/** Overwrite attempted, but what this session observed is no longer the live content. */
+ | "changed_since_observation"
+/** Exclusive create lost: the target already exists. */
+ | "target_exists"
+/** The target no longer exists: removed between preparing the mutation and writing it. */
+ | "target_missing"
+/**
+ * The target still exists but can no longer be read: replaced by a directory, made
+ * unreadable, locked, or rewritten as content this reader cannot parse. Distinct from a
+ * content change because there is nothing to diff, and from a deletion because the path is
+ * still occupied.
+ */
+ | "target_unreadable"
+/** The presented tag was never minted in this session's snapshot store. */
+ | "foreign_snapshot";
+/**
+ * Correlation only.
+ *
+ * Flora, 2026-08-13: identity "must never grant permission or identify a current owner or
+ * culprit". So this describes the writer being *rejected*, never a winner, and nothing in
+ * this module reads it to decide whether a mutation is admitted. A record of the last Atomic
+ * writer could not prove ownership anyway, because shell commands, external programs, other
+ * Atomic processes and symlink changes all bypass this coordinator.
+ */
+export interface MutationRequester {
+    readonly sessionId: string;
+    /** Session that spawned this one, from the child's `supervisor.supervisorSessionId`. */
+    readonly parentSessionId?: string;
+    readonly workflowRunId?: string;
+    readonly workflowStageId?: string;
+    readonly workflowStageName?: string;
+    readonly subagentRunId?: string;
+    readonly subagentAgent?: string;
+    /**
+     * Position within a fan-out. Needed to tell siblings apart: a child's intercom address is
+     * `agent + runId + index` (`resolveSubagentIntercomTarget`), so a stage that spawns several
+     * children of one agent onto one file yields identical identity without it.
+     */
+    readonly subagentIndex?: number;
+    /** Opaque per-attempt UUID. Diagnostic only; never an authority. */
+    readonly attemptId?: string;
+    /** The specific tool call rejected. Narrower than the attempt, which makes many calls. */
+    readonly toolCallId?: string;
+}
+/**
+ * Resolved per execution rather than captured once.
+ *
+ * Mirrors `sessionTempDir` in the session tool registry, which is a thunk "so bash spill
+ * files follow the live transcript session across fork/branch/resume". A requester captured
+ * at tool-construction time would keep a stale session id through exactly those transitions,
+ * which is the relaunch case this feature exists to make legible.
+ *
+ * Takes the tool call id rather than leaving callers to merge it in, because it has a
+ * different lifetime from the rest: session identity belongs to the session, the call id is
+ * an argument of the single `execute` being rejected.
+ */
+export type MutationRequesterResolver = (toolCallId: string) => MutationRequester | undefined;
+/**
+ * What actually diverged, so a conflict can be acted on without a second round trip.
+ *
+ * A reason and a path are not evidence; they say a race happened, not what it did. Whatever acts
+ * on the rejection, a workflow applying its own control behavior or a human reading the error,
+ * needs the divergence itself before it can decide anything.
+ *
+ * The span is computed by trimming the common prefix and suffix rather than comparing line by
+ * line positionally, so inserting one line at the top reports one changed region and not every
+ * following line.
+ */
+export interface FileMutationConflictEvidence {
+    /** 1-based line of the first divergence. */
+    readonly line: number;
+    /** Lines the rejected mutation assumed occupied the divergent span. */
+    readonly assumedLines: number;
+    /** Lines actually occupying it now. */
+    readonly foundLines: number;
+    /** First assumed line, clamped. Absent when the span is pure insertion. */
+    readonly assumed?: string;
+    /** First live line, clamped. Absent when the span is pure deletion. */
+    readonly found?: string;
+}
+/**
+ * The target as it stood at the moment of refusal, independent of any comparison.
+ *
+ * Kept separate from {@link FileMutationConflictEvidence} because the two answer different
+ * questions and only one of them can be unanswerable. A conflict may have nothing to diff
+ * against, as when the session never read the file, but there is still always something worth
+ * reporting about what the mutation was aimed at. Size in particular is the difference between
+ * clobbering an empty placeholder and clobbering four hundred lines of production code.
+ */
+export interface FileMutationLiveState {
+    /** Lines currently in the file. Zero when it is empty or does not exist. */
+    readonly lines: number;
+    /** Tag of the live content, so a rejected tag can be told apart from the real one. */
+    readonly tag?: string;
+    /** First line, clamped. Absent when the file is missing, empty, or starts with a blank line. */
+    readonly firstLine?: string;
+}
+/** Describe live content, or a missing target when `live` is `undefined`. */
+export declare function computeLiveState(live: string | undefined): FileMutationLiveState;
+/**
+ * Compare what a mutation assumed against what is live, returning `undefined` when they agree.
+ *
+ * Both sides must already share a line-ending convention. `Snapshot.text` is normalized to LF,
+ * so a caller passing raw live bytes on Windows would report every line as divergent.
+ */
+export declare function computeConflictEvidence(assumed: string, found: string): FileMutationConflictEvidence | undefined;
+export interface FileMutationConflictDetails {
+    readonly reason: FileMutationConflictReason;
+    /** Display path, as the model referred to it. */
+    readonly path: string;
+    /** Symlink-resolved key, from `canonicalMutationKey`. */
+    readonly canonicalKey: string;
+    readonly requester?: MutationRequester;
+    /** The tag the rejected mutation presented, when it had one. */
+    readonly presentedTag?: string;
+    /** Absent when the reason carries no comparison, as with `no_prior_observation`. */
+    readonly evidence?: FileMutationConflictEvidence;
+    /** What the mutation was aimed at. Absent only when it could not be read at all. */
+    readonly liveState?: FileMutationLiveState;
+    /**
+     * Filesystem error code that classified the conflict, such as `EISDIR` or `EACCES`. For a
+     * target that became unreadable this is the whole diagnosis, since nothing else about the
+     * file can be reported once the read fails.
+     */
+    readonly causeCode?: string;
+}
+/**
+ * Raised instead of a bare `Error` so a conflict is countable rather than merely readable.
+ * The message is the wire format; see {@link FILE_MUTATION_CONFLICT_CODE}.
+ */
+export declare class FileMutationConflict extends Error {
+    readonly reason: FileMutationConflictReason;
+    readonly path: string;
+    readonly canonicalKey: string;
+    readonly requester: MutationRequester | undefined;
+    readonly presentedTag: string | undefined;
+    /** Structured alongside the message so a ledger can record it without re-parsing text. */
+    readonly evidence: FileMutationConflictEvidence | undefined;
+    readonly liveState: FileMutationLiveState | undefined;
+    readonly causeCode: string | undefined;
+    constructor(details: FileMutationConflictDetails);
+    /**
+     * Ordered by what must survive truncation: the code first, then the reason and guidance,
+     * then the divergence, and the live-state summary last. The tail is the most expendable
+     * because it is the part a reader can always recover by opening the file.
+     */
+    static formatMessage(details: FileMutationConflictDetails): string;
+}
+/** Whether a thrown value is an exclusive-create collision reported by the filesystem. */
+export declare function isExclusiveCreateCollision(error: unknown): boolean;
+/**
+ * Whether a thrown value says the target is gone. `ENOTDIR` counts because a parent directory
+ * replaced by a file makes the path unreachable for the same reason a deletion does.
+ */
+export declare function isMissingTargetError(error: unknown): boolean;
+/** The `code` a filesystem rejection carries, when it carries one. */
+export declare function filesystemErrorCode(error: unknown): string | undefined;
+/**
+ * Guard for the window between preparing a mutation and committing it, called under the
+ * mutation queue.
+ *
+ * `prepared` is the content the mutation was computed against, which for a hashline edit is
+ * the file as `prepare` read it, NOT what the session originally observed, since `prepare`
+ * re-reads and may have recovered onto drifted content. Naming that honestly matters: this
+ * closes a time-of-check window, it does not prove the session read the file.
+ *
+ * Full text rather than tags: a hashline tag is 16 bits and the engine documents that it can
+ * collide, so it is a label for the model to recognize, never proof of identity.
+ */
+export declare function assertLiveMatchesPrepared(args: {
+    readonly canonicalKey: string;
+    readonly path: string;
+    readonly prepared: string;
+    readonly live: string;
+    readonly requester?: MutationRequester;
+    readonly presentedTag?: string;
+}): void;
+/**
+ * Guard for `write` overwriting an existing file: this session must already have observed the
+ * exact content it is about to replace.
+ *
+ * Asks the session's own store and never another session's, which is what keeps cross-session
+ * rejection strict. `byHashAndText` answers both halves of the requirement at once, since a
+ * hit means this session recorded exactly this content for this path.
+ *
+ * `storeKey` is the snapshot store's own key convention, the normalized absolute path, which
+ * is NOT symlink-resolved unlike `canonicalKey`. Passing the wrong one makes a symlinked path
+ * miss and report a false `no_prior_observation`.
+ *
+ * The tag is derived here rather than accepted. Unlike the engine's own use of
+ * `byHashAndText`, where the hash is the independent claim a section presented, `write` has no
+ * presented tag: it replaces the whole file. Any tag is therefore just `live` hashed, and
+ * taking it as a parameter only creates a way for the two to disagree silently.
+ */
+export declare function assertPriorSessionObservation(args: {
+    readonly canonicalKey: string;
+    readonly storeKey: string;
+    readonly path: string;
+    readonly store: SnapshotStore;
+    readonly live: string;
+    readonly requester?: MutationRequester;
+}): void;
+/**
+ * Build a requester from parts already present on a session. Kept pure so it is testable
+ * without constructing an `AgentSession`, and so this module never imports one.
+ */
+export declare function buildMutationRequester(parts: {
+    readonly sessionId: string;
+    readonly orchestration?: {
+        readonly kind: string;
+        readonly workflowRunId: string;
+        readonly workflowStageId: string;
+        readonly workflowStageName: string;
+    };
+    readonly intercom?: {
+        readonly runId: string;
+        readonly agent: string;
+        readonly index?: number;
+        readonly supervisor?: {
+            readonly supervisorSessionId: string;
+        };
+    };
+    readonly attemptId?: string;
+    readonly toolCallId?: string;
+}): MutationRequester;
+//# sourceMappingURL=file-mutation-coordinator.d.ts.map

package/dist/core/tools/file-mutation-coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-mutation-coordinator.d.ts","sourceRoot":"","sources":["../../../src/core/tools/file-mutation-coordinator.ts"],"names":[],"mappings":"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"}

package/dist/core/tools/file-mutation-coordinator.js

@@ -0,0 +1,300 @@
+import { computeFileHash } from "./hashline-engine/index.js";
+/**
+ * Stable token carried inside every conflict message.
+ *
+ * It lives in the message text, not only on the class, because nothing typed survives the
+ * trip from a tool to a workflow: a subagent result reports `cause`/`error` as strings, a
+ * workflow task result has no error field at all, and a workflow runner reduces a failure to
+ * `err.message`. Matching this token is how a consumer downstream of that flattening tells a
+ * mutation conflict apart from an ordinary tool error.
+ *
+ * It is placed at the start of the message so it survives truncation of the tail as the
+ * message is relayed. Never change it without updating every consumer that matches on it.
+ */
+export const FILE_MUTATION_CONFLICT_CODE = "FILE_MUTATION_CONFLICT";
+/**
+ * Excerpts are clamped because a conflict travels as message text through channels that
+ * truncate, and because file content copied into an error outlives the turn in ledger records.
+ * One line per side is enough to tell the model whether its plan still holds.
+ */
+const EVIDENCE_LINE_CHARS = 120;
+function clampLine(line) {
+    return line.length <= EVIDENCE_LINE_CHARS ? line : `${line.slice(0, EVIDENCE_LINE_CHARS)}...`;
+}
+/** Describe live content, or a missing target when `live` is `undefined`. */
+export function computeLiveState(live) {
+    if (live === undefined)
+        return { lines: 0 };
+    // Trailing newline terminates the last line rather than starting an empty one.
+    const lines = live === "" ? [] : live.replace(/\n$/, "").split("\n");
+    const first = lines[0];
+    return {
+        lines: lines.length,
+        tag: computeFileHash(live),
+        ...(first ? { firstLine: clampLine(first) } : {}),
+    };
+}
+/**
+ * Compare what a mutation assumed against what is live, returning `undefined` when they agree.
+ *
+ * Both sides must already share a line-ending convention. `Snapshot.text` is normalized to LF,
+ * so a caller passing raw live bytes on Windows would report every line as divergent.
+ */
+export function computeConflictEvidence(assumed, found) {
+    if (assumed === found)
+        return undefined;
+    const assumedLines = assumed.split("\n");
+    const foundLines = found.split("\n");
+    let start = 0;
+    while (start < assumedLines.length && start < foundLines.length && assumedLines[start] === foundLines[start]) {
+        start++;
+    }
+    let endAssumed = assumedLines.length;
+    let endFound = foundLines.length;
+    while (endAssumed > start && endFound > start && assumedLines[endAssumed - 1] === foundLines[endFound - 1]) {
+        endAssumed--;
+        endFound--;
+    }
+    return {
+        line: start + 1,
+        assumedLines: endAssumed - start,
+        foundLines: endFound - start,
+        ...(start < endAssumed ? { assumed: clampLine(assumedLines[start] ?? "") } : {}),
+        ...(start < endFound ? { found: clampLine(foundLines[start] ?? "") } : {}),
+    };
+}
+/**
+ * Paired so the instruction cannot contradict the diagnosis it follows.
+ *
+ * A single shared instruction cannot be true of all six reasons. "Read the file again" is
+ * false for the two that fail precisely because the file was never read, and impossible for
+ * `target_missing`, where there is nothing left to read.
+ */
+const REASON_COPY = {
+    changed_before_write: {
+        diagnosis: "the file changed after this edit was prepared",
+        instruction: "Read the file again and rebuild this edit from what it says now; do not resend it unchanged.",
+    },
+    no_prior_observation: {
+        diagnosis: "this session has not read the file it is overwriting",
+        instruction: "Read the file first, then decide whether this overwrite is still the change you want.",
+    },
+    changed_since_observation: {
+        diagnosis: "the file changed since this session last read it",
+        instruction: "Read the file again and reconcile this change with what is there now.",
+    },
+    target_exists: {
+        diagnosis: "the file already exists",
+        instruction: "Read the existing file and edit it in place, or write to a different path.",
+    },
+    target_missing: {
+        diagnosis: "the file no longer exists",
+        instruction: "Do not read it; confirm the removal was intended, then recreate the file or drop this change.",
+    },
+    target_unreadable: {
+        diagnosis: "the file still exists but could no longer be read",
+        instruction: "Something replaced or locked the path rather than editing it. Inspect what is there now before retrying; a second identical edit will fail the same way.",
+    },
+    foreign_snapshot: {
+        diagnosis: "the snapshot tag was not issued in this session",
+        instruction: "Read the file in this session to obtain a valid tag before editing it.",
+    },
+};
+function describeRequester(requester) {
+    if (!requester)
+        return "";
+    const parts = [`session=${requester.sessionId}`];
+    if (requester.parentSessionId)
+        parts.push(`parent=${requester.parentSessionId}`);
+    if (requester.workflowRunId)
+        parts.push(`run=${requester.workflowRunId}`);
+    if (requester.workflowStageId)
+        parts.push(`stage=${requester.workflowStageId}`);
+    // Quoted: a stage name is free text and the field separator here is a space.
+    if (requester.workflowStageName)
+        parts.push(`stageName="${requester.workflowStageName}"`);
+    if (requester.subagentRunId)
+        parts.push(`child=${requester.subagentRunId}`);
+    if (requester.subagentAgent)
+        parts.push(`agent=${requester.subagentAgent}`);
+    // Presence, not truthiness: the first child of a fan-out is index 0.
+    if (requester.subagentIndex !== undefined)
+        parts.push(`index=${requester.subagentIndex}`);
+    if (requester.attemptId)
+        parts.push(`attempt=${requester.attemptId}`);
+    if (requester.toolCallId)
+        parts.push(`call=${requester.toolCallId}`);
+    return ` [${parts.join(" ")}]`;
+}
+/**
+ * Quote an excerpt of file content for inclusion in a single-line message.
+ *
+ * `JSON.stringify` rather than wrapping in backticks or quotes of our own: source lines
+ * routinely contain both, and a template literal in a TypeScript file would otherwise close
+ * the delimiter early and leave the excerpt unreadable. It also escapes control characters,
+ * so a stray CR from a file this module was handed unnormalized shows up as `\r` rather than
+ * silently rearranging the message.
+ */
+function quoteExcerpt(text) {
+    return JSON.stringify(text);
+}
+function describeEvidence(evidence) {
+    if (!evidence)
+        return "";
+    const span = evidence.assumedLines === 1 && evidence.foundLines === 1
+        ? ""
+        : ` (${evidence.assumedLines} lines replaced by ${evidence.foundLines})`;
+    const at = ` First divergence at line ${evidence.line}`;
+    if (evidence.assumed !== undefined && evidence.found !== undefined) {
+        return `${at}: assumed ${quoteExcerpt(evidence.assumed)}, found ${quoteExcerpt(evidence.found)}${span}.`;
+    }
+    if (evidence.found !== undefined) {
+        return `${at}: found ${quoteExcerpt(evidence.found)} where this mutation expected nothing${span}.`;
+    }
+    return `${at}: assumed ${quoteExcerpt(evidence.assumed ?? "")}, which is no longer present${span}.`;
+}
+function describeLiveState(state) {
+    if (!state)
+        return "";
+    if (!state.tag)
+        return " The target does not exist.";
+    const first = state.firstLine ? `, starting ${quoteExcerpt(state.firstLine)}` : "";
+    return ` Target now holds ${state.lines} lines, #${state.tag}${first}.`;
+}
+/**
+ * Raised instead of a bare `Error` so a conflict is countable rather than merely readable.
+ * The message is the wire format; see {@link FILE_MUTATION_CONFLICT_CODE}.
+ */
+export class FileMutationConflict extends Error {
+    constructor(details) {
+        super(FileMutationConflict.formatMessage(details));
+        // Sub-classing Error does not set this, and consumers match on it.
+        this.name = "FileMutationConflict";
+        this.reason = details.reason;
+        this.path = details.path;
+        this.canonicalKey = details.canonicalKey;
+        this.requester = details.requester;
+        this.presentedTag = details.presentedTag;
+        this.evidence = details.evidence;
+        this.liveState = details.liveState;
+        this.causeCode = details.causeCode;
+    }
+    /**
+     * Ordered by what must survive truncation: the code first, then the reason and guidance,
+     * then the divergence, and the live-state summary last. The tail is the most expendable
+     * because it is the part a reader can always recover by opening the file.
+     */
+    static formatMessage(details) {
+        const tag = details.presentedTag ? ` (presented #${details.presentedTag})` : "";
+        const copy = REASON_COPY[details.reason];
+        const cause = details.causeCode ? ` (${details.causeCode})` : "";
+        return (`${FILE_MUTATION_CONFLICT_CODE}:${details.reason} ${details.path}${tag}: ` +
+            `${copy.diagnosis}${cause}.${describeRequester(details.requester)} ` +
+            copy.instruction +
+            describeEvidence(details.evidence) +
+            describeLiveState(details.liveState));
+    }
+}
+/** Whether a thrown value is an exclusive-create collision reported by the filesystem. */
+export function isExclusiveCreateCollision(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST";
+}
+/**
+ * Whether a thrown value says the target is gone. `ENOTDIR` counts because a parent directory
+ * replaced by a file makes the path unreachable for the same reason a deletion does.
+ */
+export function isMissingTargetError(error) {
+    const code = filesystemErrorCode(error);
+    return code === "ENOENT" || code === "ENOTDIR";
+}
+/** The `code` a filesystem rejection carries, when it carries one. */
+export function filesystemErrorCode(error) {
+    if (typeof error !== "object" || error === null || !("code" in error))
+        return undefined;
+    const code = error.code;
+    return typeof code === "string" ? code : undefined;
+}
+/**
+ * Guard for the window between preparing a mutation and committing it, called under the
+ * mutation queue.
+ *
+ * `prepared` is the content the mutation was computed against, which for a hashline edit is
+ * the file as `prepare` read it, NOT what the session originally observed, since `prepare`
+ * re-reads and may have recovered onto drifted content. Naming that honestly matters: this
+ * closes a time-of-check window, it does not prove the session read the file.
+ *
+ * Full text rather than tags: a hashline tag is 16 bits and the engine documents that it can
+ * collide, so it is a label for the model to recognize, never proof of identity.
+ */
+export function assertLiveMatchesPrepared(args) {
+    if (args.live === args.prepared)
+        return;
+    const evidence = computeConflictEvidence(args.prepared, args.live);
+    throw new FileMutationConflict({
+        reason: "changed_before_write",
+        path: args.path,
+        canonicalKey: args.canonicalKey,
+        requester: args.requester,
+        presentedTag: args.presentedTag,
+        liveState: computeLiveState(args.live),
+        ...(evidence ? { evidence } : {}),
+    });
+}
+/**
+ * Guard for `write` overwriting an existing file: this session must already have observed the
+ * exact content it is about to replace.
+ *
+ * Asks the session's own store and never another session's, which is what keeps cross-session
+ * rejection strict. `byHashAndText` answers both halves of the requirement at once, since a
+ * hit means this session recorded exactly this content for this path.
+ *
+ * `storeKey` is the snapshot store's own key convention, the normalized absolute path, which
+ * is NOT symlink-resolved unlike `canonicalKey`. Passing the wrong one makes a symlinked path
+ * miss and report a false `no_prior_observation`.
+ *
+ * The tag is derived here rather than accepted. Unlike the engine's own use of
+ * `byHashAndText`, where the hash is the independent claim a section presented, `write` has no
+ * presented tag: it replaces the whole file. Any tag is therefore just `live` hashed, and
+ * taking it as a parameter only creates a way for the two to disagree silently.
+ */
+export function assertPriorSessionObservation(args) {
+    if (args.store.byHashAndText(args.storeKey, computeFileHash(args.live), args.live))
+        return;
+    // The last version this session recorded is what it believed it was overwriting, so the
+    // divergence from live is the evidence. Without one there is nothing to diff, but the live
+    // state still reports what was about to be clobbered sight unseen, which is the part
+    // whoever reviews the rejection actually needs.
+    const head = args.store.head(args.storeKey);
+    const evidence = head ? computeConflictEvidence(head.text, args.live) : undefined;
+    throw new FileMutationConflict({
+        reason: head ? "changed_since_observation" : "no_prior_observation",
+        path: args.path,
+        canonicalKey: args.canonicalKey,
+        requester: args.requester,
+        liveState: computeLiveState(args.live),
+        ...(evidence ? { evidence } : {}),
+    });
+}
+/**
+ * Build a requester from parts already present on a session. Kept pure so it is testable
+ * without constructing an `AgentSession`, and so this module never imports one.
+ */
+export function buildMutationRequester(parts) {
+    const workflow = parts.orchestration?.kind === "workflow-stage" ? parts.orchestration : undefined;
+    const supervisorSessionId = parts.intercom?.supervisor?.supervisorSessionId;
+    const subagentIndex = parts.intercom?.index;
+    return {
+        sessionId: parts.sessionId,
+        ...(supervisorSessionId ? { parentSessionId: supervisorSessionId } : {}),
+        ...(workflow ? { workflowRunId: workflow.workflowRunId } : {}),
+        ...(workflow ? { workflowStageId: workflow.workflowStageId } : {}),
+        ...(workflow ? { workflowStageName: workflow.workflowStageName } : {}),
+        ...(parts.intercom ? { subagentRunId: parts.intercom.runId } : {}),
+        ...(parts.intercom ? { subagentAgent: parts.intercom.agent } : {}),
+        // Presence, not truthiness: index 0 is the first child, and `0 ? … : {}` drops it.
+        ...(subagentIndex !== undefined ? { subagentIndex } : {}),
+        ...(parts.attemptId ? { attemptId: parts.attemptId } : {}),
+        ...(parts.toolCallId ? { toolCallId: parts.toolCallId } : {}),
+    };
+}
+//# sourceMappingURL=file-mutation-coordinator.js.map

package/dist/core/tools/file-mutation-coordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-mutation-coordinator.js","sourceRoot":"","sources":["../../../src/core/tools/file-mutation-coordinator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAsB,MAAM,4BAA4B,CAAC;AAEjF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,wBAAwB,CAAC;AAqGpE;;;;GAIG;AACH,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAEhC,SAAS,SAAS,CAAC,IAAY;IAC9B,OAAO,IAAI,CAAC,MAAM,IAAI,mBAAmB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,mBAAmB,CAAC,KAAK,CAAC;AAC/F,CAAC;AAoBD,6EAA6E;AAC7E,MAAM,UAAU,gBAAgB,CAAC,IAAwB;IACxD,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAC5C,+EAA+E;IAC/E,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACrE,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACvB,OAAO;QACN,KAAK,EAAE,KAAK,CAAC,MAAM;QACnB,GAAG,EAAE,eAAe,CAAC,IAAI,CAAC;QAC1B,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACjD,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAe,EAAE,KAAa;IACrE,IAAI,OAAO,KAAK,KAAK;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,YAAY,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,OAAO,KAAK,GAAG,YAAY,CAAC,MAAM,IAAI,KAAK,GAAG,UAAU,CAAC,MAAM,IAAI,YAAY,CAAC,KAAK,CAAC,KAAK,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9G,KAAK,EAAE,CAAC;IACT,CAAC;IACD,IAAI,UAAU,GAAG,YAAY,CAAC,MAAM,CAAC;IACrC,IAAI,QAAQ,GAAG,UAAU,CAAC,MAAM,CAAC;IACjC,OAAO,UAAU,GAAG,KAAK,IAAI,QAAQ,GAAG,KAAK,IAAI,YAAY,CAAC,UAAU,GAAG,CAAC,CAAC,KAAK,UAAU,CAAC,QAAQ,GAAG,CAAC,CAAC,EAAE,CAAC;QAC5G,UAAU,EAAE,CAAC;QACb,QAAQ,EAAE,CAAC;IACZ,CAAC;IACD,OAAO;QACN,IAAI,EAAE,KAAK,GAAG,CAAC;QACf,YAAY,EAAE,UAAU,GAAG,KAAK;QAChC,UAAU,EAAE,QAAQ,GAAG,KAAK;QAC5B,GAAG,CAAC,KAAK,GAAG,UAAU,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChF,GAAG,CAAC,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1E,CAAC;AACH,CAAC;AA8BD;;;;;;GAMG;AACH,MAAM,WAAW,GAAmD;IACnE,oBAAoB,EAAE;QACrB,SAAS,EAAE,+CAA+C;QAC1D,WAAW,EAAE,8FAA8F;KAC3G;IACD,oBAAoB,EAAE;QACrB,SAAS,EAAE,sDAAsD;QACjE,WAAW,EAAE,uFAAuF;KACpG;IACD,yBAAyB,EAAE;QAC1B,SAAS,EAAE,kDAAkD;QAC7D,WAAW,EAAE,uEAAuE;KACpF;IACD,aAAa,EAAE;QACd,SAAS,EAAE,yBAAyB;QACpC,WAAW,EAAE,4EAA4E;KACzF;IACD,cAAc,EAAE;QACf,SAAS,EAAE,2BAA2B;QACtC,WAAW,EAAE,+FAA+F;KAC5G;IACD,iBAAiB,EAAE;QAClB,SAAS,EAAE,mDAAmD;QAC9D,WAAW,EACV,0JAA0J;KAC3J;IACD,gBAAgB,EAAE;QACjB,SAAS,EAAE,iDAAiD;QAC5D,WAAW,EAAE,wEAAwE;KACrF;CACD,CAAC;AAEF,SAAS,iBAAiB,CAAC,SAAwC;IAClE,IAAI,CAAC,SAAS;QAAE,OAAO,EAAE,CAAC;IAC1B,MAAM,KAAK,GAAG,CAAC,WAAW,SAAS,CAAC,SAAS,EAAE,CAAC,CAAC;IACjD,IAAI,SAAS,CAAC,eAAe;QAAE,KAAK,CAAC,IAAI,CAAC,UAAU,SAAS,CAAC,eAAe,EAAE,CAAC,CAAC;IACjF,IAAI,SAAS,CAAC,aAAa;QAAE,KAAK,CAAC,IAAI,CAAC,OAAO,SAAS,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1E,IAAI,SAAS,CAAC,eAAe;QAAE,KAAK,CAAC,IAAI,CAAC,SAAS,SAAS,CAAC,eAAe,EAAE,CAAC,CAAC;IAChF,6EAA6E;IAC7E,IAAI,SAAS,CAAC,iBAAiB;QAAE,KAAK,CAAC,IAAI,CAAC,cAAc,SAAS,CAAC,iBAAiB,GAAG,CAAC,CAAC;IAC1F,IAAI,SAAS,CAAC,aAAa;QAAE,KAAK,CAAC,IAAI,CAAC,SAAS,SAAS,CAAC,aAAa,EAAE,CAAC,CAAC;IAC5E,IAAI,SAAS,CAAC,aAAa;QAAE,KAAK,CAAC,IAAI,CAAC,SAAS,SAAS,CAAC,aAAa,EAAE,CAAC,CAAC;IAC5E,qEAAqE;IACrE,IAAI,SAAS,CAAC,aAAa,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,SAAS,SAAS,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1F,IAAI,SAAS,CAAC,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,WAAW,SAAS,CAAC,SAAS,EAAE,CAAC,CAAC;IACtE,IAAI,SAAS,CAAC,UAAU;QAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,SAAS,CAAC,UAAU,EAAE,CAAC,CAAC;IACrE,OAAO,KAAK,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAChC,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,YAAY,CAAC,IAAY;IACjC,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,SAAS,gBAAgB,CAAC,QAAkD;IAC3E,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,CAAC;IACzB,MAAM,IAAI,GACT,QAAQ,CAAC,YAAY,KAAK,CAAC,IAAI,QAAQ,CAAC,UAAU,KAAK,CAAC;QACvD,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,KAAK,QAAQ,CAAC,YAAY,sBAAsB,QAAQ,CAAC,UAAU,GAAG,CAAC;IAC3E,MAAM,EAAE,GAAG,6BAA6B,QAAQ,CAAC,IAAI,EAAE,CAAC;IACxD,IAAI,QAAQ,CAAC,OAAO,KAAK,SAAS,IAAI,QAAQ,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QACpE,OAAO,GAAG,EAAE,aAAa,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,WAAW,YAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,IAAI,GAAG,CAAC;IAC1G,CAAC;IACD,IAAI,QAAQ,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAClC,OAAO,GAAG,EAAE,WAAW,YAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,wCAAwC,IAAI,GAAG,CAAC;IACpG,CAAC;IACD,OAAO,GAAG,EAAE,aAAa,YAAY,CAAC,QAAQ,CAAC,OAAO,IAAI,EAAE,CAAC,+BAA+B,IAAI,GAAG,CAAC;AACrG,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAwC;IAClE,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IACtB,IAAI,CAAC,KAAK,CAAC,GAAG;QAAE,OAAO,6BAA6B,CAAC;IACrD,MAAM,KAAK,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,cAAc,YAAY,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACnF,OAAO,qBAAqB,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,GAAG,GAAG,KAAK,GAAG,CAAC;AACzE,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAW9C,YAAY,OAAoC;QAC/C,KAAK,CAAC,oBAAoB,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;QACnD,mEAAmE;QACnE,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;QACzC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;QACzC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACpC,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,aAAa,CAAC,OAAoC;QACxD,MAAM,GAAG,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,gBAAgB,OAAO,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAChF,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACzC,MAAM,KAAK,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACjE,OAAO,CACN,GAAG,2BAA2B,IAAI,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,IAAI,GAAG,GAAG,IAAI;YAC1E,GAAG,IAAI,CAAC,SAAS,GAAG,KAAK,IAAI,iBAAiB,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG;YACpE,IAAI,CAAC,WAAW;YAChB,gBAAgB,CAAC,OAAO,CAAC,QAAQ,CAAC;YAClC,iBAAiB,CAAC,OAAO,CAAC,SAAS,CAAC,CACpC,CAAC;IACH,CAAC;CACD;AAED,0FAA0F;AAC1F,MAAM,UAAU,0BAA0B,CAAC,KAAc;IACxD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC;AAClG,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc;IAClD,MAAM,IAAI,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IACxC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,SAAS,CAAC;AAChD,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,mBAAmB,CAAC,KAAc;IACjD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACxF,MAAM,IAAI,GAAI,KAA4B,CAAC,IAAI,CAAC;IAChD,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AACpD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAOzC;IACA,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,QAAQ;QAAE,OAAO;IACxC,MAAM,QAAQ,GAAG,uBAAuB,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IACnE,MAAM,IAAI,oBAAoB,CAAC;QAC9B,MAAM,EAAE,sBAAsB;QAC9B,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,SAAS,EAAE,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC;QACtC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACjC,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,6BAA6B,CAAC,IAO7C;IACA,IAAI,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,CAAC,QAAQ,EAAE,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO;IAC3F,wFAAwF;IACxF,2FAA2F;IAC3F,qFAAqF;IACrF,gDAAgD;IAChD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC,uBAAuB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAClF,MAAM,IAAI,oBAAoB,CAAC;QAC9B,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,2BAA2B,CAAC,CAAC,CAAC,sBAAsB;QACnE,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,SAAS,EAAE,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC;QACtC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACjC,CAAC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAgBtC;IACA,MAAM,QAAQ,GAAG,KAAK,CAAC,aAAa,EAAE,IAAI,KAAK,gBAAgB,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC;IAClG,MAAM,mBAAmB,GAAG,KAAK,CAAC,QAAQ,EAAE,UAAU,EAAE,mBAAmB,CAAC;IAC5E,MAAM,aAAa,GAAG,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC;IAC5C,OAAO;QACN,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,GAAG,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,mBAAmB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxE,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,QAAQ,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClE,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,QAAQ,CAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtE,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClE,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClE,mFAAmF;QACnF,GAAG,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzD,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1D,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC7D,CAAC;AACH,CAAC","sourcesContent":["import { computeFileHash, type SnapshotStore } from \"./hashline-engine/index.ts\";\n\n/**\n * Stable token carried inside every conflict message.\n *\n * It lives in the message text, not only on the class, because nothing typed survives the\n * trip from a tool to a workflow: a subagent result reports `cause`/`error` as strings, a\n * workflow task result has no error field at all, and a workflow runner reduces a failure to\n * `err.message`. Matching this token is how a consumer downstream of that flattening tells a\n * mutation conflict apart from an ordinary tool error.\n *\n * It is placed at the start of the message so it survives truncation of the tail as the\n * message is relayed. Never change it without updating every consumer that matches on it.\n */\nexport const FILE_MUTATION_CONFLICT_CODE = \"FILE_MUTATION_CONFLICT\";\n\n/**\n * Reasons report a {@link FileMutationLiveState} wherever the live target can be described,\n * which is everywhere except `target_unreadable`: that one exists precisely because the target\n * could not be read, so claiming a size or a tag for it would be invention.\n *\n * Only the reasons that have something to compare against also report a\n * {@link FileMutationConflictEvidence} diff: `no_prior_observation` never read the file, and\n * `foreign_snapshot` presented a tag naming content this session has never seen, so in both\n * cases there is no prior side to diff.\n */\nexport type FileMutationConflictReason =\n\t/** Live content moved between the mutation being prepared and the write being attempted. */\n\t| \"changed_before_write\"\n\t/** Overwrite attempted with no prior read of this file in this session. */\n\t| \"no_prior_observation\"\n\t/** Overwrite attempted, but what this session observed is no longer the live content. */\n\t| \"changed_since_observation\"\n\t/** Exclusive create lost: the target already exists. */\n\t| \"target_exists\"\n\t/** The target no longer exists: removed between preparing the mutation and writing it. */\n\t| \"target_missing\"\n\t/**\n\t * The target still exists but can no longer be read: replaced by a directory, made\n\t * unreadable, locked, or rewritten as content this reader cannot parse. Distinct from a\n\t * content change because there is nothing to diff, and from a deletion because the path is\n\t * still occupied.\n\t */\n\t| \"target_unreadable\"\n\t/** The presented tag was never minted in this session's snapshot store. */\n\t| \"foreign_snapshot\";\n\n/**\n * Correlation only.\n *\n * Flora, 2026-08-13: identity \"must never grant permission or identify a current owner or\n * culprit\". So this describes the writer being *rejected*, never a winner, and nothing in\n * this module reads it to decide whether a mutation is admitted. A record of the last Atomic\n * writer could not prove ownership anyway, because shell commands, external programs, other\n * Atomic processes and symlink changes all bypass this coordinator.\n */\nexport interface MutationRequester {\n\treadonly sessionId: string;\n\t/** Session that spawned this one, from the child's `supervisor.supervisorSessionId`. */\n\treadonly parentSessionId?: string;\n\treadonly workflowRunId?: string;\n\treadonly workflowStageId?: string;\n\treadonly workflowStageName?: string;\n\treadonly subagentRunId?: string;\n\treadonly subagentAgent?: string;\n\t/**\n\t * Position within a fan-out. Needed to tell siblings apart: a child's intercom address is\n\t * `agent + runId + index` (`resolveSubagentIntercomTarget`), so a stage that spawns several\n\t * children of one agent onto one file yields identical identity without it.\n\t */\n\treadonly subagentIndex?: number;\n\t/** Opaque per-attempt UUID. Diagnostic only; never an authority. */\n\treadonly attemptId?: string;\n\t/** The specific tool call rejected. Narrower than the attempt, which makes many calls. */\n\treadonly toolCallId?: string;\n}\n\n/**\n * Resolved per execution rather than captured once.\n *\n * Mirrors `sessionTempDir` in the session tool registry, which is a thunk \"so bash spill\n * files follow the live transcript session across fork/branch/resume\". A requester captured\n * at tool-construction time would keep a stale session id through exactly those transitions,\n * which is the relaunch case this feature exists to make legible.\n *\n * Takes the tool call id rather than leaving callers to merge it in, because it has a\n * different lifetime from the rest: session identity belongs to the session, the call id is\n * an argument of the single `execute` being rejected.\n */\nexport type MutationRequesterResolver = (toolCallId: string) => MutationRequester | undefined;\n\n/**\n * What actually diverged, so a conflict can be acted on without a second round trip.\n *\n * A reason and a path are not evidence; they say a race happened, not what it did. Whatever acts\n * on the rejection, a workflow applying its own control behavior or a human reading the error,\n * needs the divergence itself before it can decide anything.\n *\n * The span is computed by trimming the common prefix and suffix rather than comparing line by\n * line positionally, so inserting one line at the top reports one changed region and not every\n * following line.\n */\nexport interface FileMutationConflictEvidence {\n\t/** 1-based line of the first divergence. */\n\treadonly line: number;\n\t/** Lines the rejected mutation assumed occupied the divergent span. */\n\treadonly assumedLines: number;\n\t/** Lines actually occupying it now. */\n\treadonly foundLines: number;\n\t/** First assumed line, clamped. Absent when the span is pure insertion. */\n\treadonly assumed?: string;\n\t/** First live line, clamped. Absent when the span is pure deletion. */\n\treadonly found?: string;\n}\n\n/**\n * Excerpts are clamped because a conflict travels as message text through channels that\n * truncate, and because file content copied into an error outlives the turn in ledger records.\n * One line per side is enough to tell the model whether its plan still holds.\n */\nconst EVIDENCE_LINE_CHARS = 120;\n\nfunction clampLine(line: string): string {\n\treturn line.length <= EVIDENCE_LINE_CHARS ? line : `${line.slice(0, EVIDENCE_LINE_CHARS)}...`;\n}\n\n/**\n * The target as it stood at the moment of refusal, independent of any comparison.\n *\n * Kept separate from {@link FileMutationConflictEvidence} because the two answer different\n * questions and only one of them can be unanswerable. A conflict may have nothing to diff\n * against, as when the session never read the file, but there is still always something worth\n * reporting about what the mutation was aimed at. Size in particular is the difference between\n * clobbering an empty placeholder and clobbering four hundred lines of production code.\n */\nexport interface FileMutationLiveState {\n\t/** Lines currently in the file. Zero when it is empty or does not exist. */\n\treadonly lines: number;\n\t/** Tag of the live content, so a rejected tag can be told apart from the real one. */\n\treadonly tag?: string;\n\t/** First line, clamped. Absent when the file is missing, empty, or starts with a blank line. */\n\treadonly firstLine?: string;\n}\n\n/** Describe live content, or a missing target when `live` is `undefined`. */\nexport function computeLiveState(live: string | undefined): FileMutationLiveState {\n\tif (live === undefined) return { lines: 0 };\n\t// Trailing newline terminates the last line rather than starting an empty one.\n\tconst lines = live === \"\" ? [] : live.replace(/\\n$/, \"\").split(\"\\n\");\n\tconst first = lines[0];\n\treturn {\n\t\tlines: lines.length,\n\t\ttag: computeFileHash(live),\n\t\t...(first ? { firstLine: clampLine(first) } : {}),\n\t};\n}\n\n/**\n * Compare what a mutation assumed against what is live, returning `undefined` when they agree.\n *\n * Both sides must already share a line-ending convention. `Snapshot.text` is normalized to LF,\n * so a caller passing raw live bytes on Windows would report every line as divergent.\n */\nexport function computeConflictEvidence(assumed: string, found: string): FileMutationConflictEvidence | undefined {\n\tif (assumed === found) return undefined;\n\tconst assumedLines = assumed.split(\"\\n\");\n\tconst foundLines = found.split(\"\\n\");\n\tlet start = 0;\n\twhile (start < assumedLines.length && start < foundLines.length && assumedLines[start] === foundLines[start]) {\n\t\tstart++;\n\t}\n\tlet endAssumed = assumedLines.length;\n\tlet endFound = foundLines.length;\n\twhile (endAssumed > start && endFound > start && assumedLines[endAssumed - 1] === foundLines[endFound - 1]) {\n\t\tendAssumed--;\n\t\tendFound--;\n\t}\n\treturn {\n\t\tline: start + 1,\n\t\tassumedLines: endAssumed - start,\n\t\tfoundLines: endFound - start,\n\t\t...(start < endAssumed ? { assumed: clampLine(assumedLines[start] ?? \"\") } : {}),\n\t\t...(start < endFound ? { found: clampLine(foundLines[start] ?? \"\") } : {}),\n\t};\n}\n\nexport interface FileMutationConflictDetails {\n\treadonly reason: FileMutationConflictReason;\n\t/** Display path, as the model referred to it. */\n\treadonly path: string;\n\t/** Symlink-resolved key, from `canonicalMutationKey`. */\n\treadonly canonicalKey: string;\n\treadonly requester?: MutationRequester;\n\t/** The tag the rejected mutation presented, when it had one. */\n\treadonly presentedTag?: string;\n\t/** Absent when the reason carries no comparison, as with `no_prior_observation`. */\n\treadonly evidence?: FileMutationConflictEvidence;\n\t/** What the mutation was aimed at. Absent only when it could not be read at all. */\n\treadonly liveState?: FileMutationLiveState;\n\t/**\n\t * Filesystem error code that classified the conflict, such as `EISDIR` or `EACCES`. For a\n\t * target that became unreadable this is the whole diagnosis, since nothing else about the\n\t * file can be reported once the read fails.\n\t */\n\treadonly causeCode?: string;\n}\n\ninterface ReasonCopy {\n\t/** Why the mutation was refused. */\n\treadonly diagnosis: string;\n\t/** What to do about it. */\n\treadonly instruction: string;\n}\n\n/**\n * Paired so the instruction cannot contradict the diagnosis it follows.\n *\n * A single shared instruction cannot be true of all six reasons. \"Read the file again\" is\n * false for the two that fail precisely because the file was never read, and impossible for\n * `target_missing`, where there is nothing left to read.\n */\nconst REASON_COPY: Record<FileMutationConflictReason, ReasonCopy> = {\n\tchanged_before_write: {\n\t\tdiagnosis: \"the file changed after this edit was prepared\",\n\t\tinstruction: \"Read the file again and rebuild this edit from what it says now; do not resend it unchanged.\",\n\t},\n\tno_prior_observation: {\n\t\tdiagnosis: \"this session has not read the file it is overwriting\",\n\t\tinstruction: \"Read the file first, then decide whether this overwrite is still the change you want.\",\n\t},\n\tchanged_since_observation: {\n\t\tdiagnosis: \"the file changed since this session last read it\",\n\t\tinstruction: \"Read the file again and reconcile this change with what is there now.\",\n\t},\n\ttarget_exists: {\n\t\tdiagnosis: \"the file already exists\",\n\t\tinstruction: \"Read the existing file and edit it in place, or write to a different path.\",\n\t},\n\ttarget_missing: {\n\t\tdiagnosis: \"the file no longer exists\",\n\t\tinstruction: \"Do not read it; confirm the removal was intended, then recreate the file or drop this change.\",\n\t},\n\ttarget_unreadable: {\n\t\tdiagnosis: \"the file still exists but could no longer be read\",\n\t\tinstruction:\n\t\t\t\"Something replaced or locked the path rather than editing it. Inspect what is there now before retrying; a second identical edit will fail the same way.\",\n\t},\n\tforeign_snapshot: {\n\t\tdiagnosis: \"the snapshot tag was not issued in this session\",\n\t\tinstruction: \"Read the file in this session to obtain a valid tag before editing it.\",\n\t},\n};\n\nfunction describeRequester(requester: MutationRequester | undefined): string {\n\tif (!requester) return \"\";\n\tconst parts = [`session=${requester.sessionId}`];\n\tif (requester.parentSessionId) parts.push(`parent=${requester.parentSessionId}`);\n\tif (requester.workflowRunId) parts.push(`run=${requester.workflowRunId}`);\n\tif (requester.workflowStageId) parts.push(`stage=${requester.workflowStageId}`);\n\t// Quoted: a stage name is free text and the field separator here is a space.\n\tif (requester.workflowStageName) parts.push(`stageName=\"${requester.workflowStageName}\"`);\n\tif (requester.subagentRunId) parts.push(`child=${requester.subagentRunId}`);\n\tif (requester.subagentAgent) parts.push(`agent=${requester.subagentAgent}`);\n\t// Presence, not truthiness: the first child of a fan-out is index 0.\n\tif (requester.subagentIndex !== undefined) parts.push(`index=${requester.subagentIndex}`);\n\tif (requester.attemptId) parts.push(`attempt=${requester.attemptId}`);\n\tif (requester.toolCallId) parts.push(`call=${requester.toolCallId}`);\n\treturn ` [${parts.join(\" \")}]`;\n}\n\n/**\n * Quote an excerpt of file content for inclusion in a single-line message.\n *\n * `JSON.stringify` rather than wrapping in backticks or quotes of our own: source lines\n * routinely contain both, and a template literal in a TypeScript file would otherwise close\n * the delimiter early and leave the excerpt unreadable. It also escapes control characters,\n * so a stray CR from a file this module was handed unnormalized shows up as `\\r` rather than\n * silently rearranging the message.\n */\nfunction quoteExcerpt(text: string): string {\n\treturn JSON.stringify(text);\n}\n\nfunction describeEvidence(evidence: FileMutationConflictEvidence | undefined): string {\n\tif (!evidence) return \"\";\n\tconst span =\n\t\tevidence.assumedLines === 1 && evidence.foundLines === 1\n\t\t\t? \"\"\n\t\t\t: ` (${evidence.assumedLines} lines replaced by ${evidence.foundLines})`;\n\tconst at = ` First divergence at line ${evidence.line}`;\n\tif (evidence.assumed !== undefined && evidence.found !== undefined) {\n\t\treturn `${at}: assumed ${quoteExcerpt(evidence.assumed)}, found ${quoteExcerpt(evidence.found)}${span}.`;\n\t}\n\tif (evidence.found !== undefined) {\n\t\treturn `${at}: found ${quoteExcerpt(evidence.found)} where this mutation expected nothing${span}.`;\n\t}\n\treturn `${at}: assumed ${quoteExcerpt(evidence.assumed ?? \"\")}, which is no longer present${span}.`;\n}\n\nfunction describeLiveState(state: FileMutationLiveState | undefined): string {\n\tif (!state) return \"\";\n\tif (!state.tag) return \" The target does not exist.\";\n\tconst first = state.firstLine ? `, starting ${quoteExcerpt(state.firstLine)}` : \"\";\n\treturn ` Target now holds ${state.lines} lines, #${state.tag}${first}.`;\n}\n\n/**\n * Raised instead of a bare `Error` so a conflict is countable rather than merely readable.\n * The message is the wire format; see {@link FILE_MUTATION_CONFLICT_CODE}.\n */\nexport class FileMutationConflict extends Error {\n\treadonly reason: FileMutationConflictReason;\n\treadonly path: string;\n\treadonly canonicalKey: string;\n\treadonly requester: MutationRequester | undefined;\n\treadonly presentedTag: string | undefined;\n\t/** Structured alongside the message so a ledger can record it without re-parsing text. */\n\treadonly evidence: FileMutationConflictEvidence | undefined;\n\treadonly liveState: FileMutationLiveState | undefined;\n\treadonly causeCode: string | undefined;\n\n\tconstructor(details: FileMutationConflictDetails) {\n\t\tsuper(FileMutationConflict.formatMessage(details));\n\t\t// Sub-classing Error does not set this, and consumers match on it.\n\t\tthis.name = \"FileMutationConflict\";\n\t\tthis.reason = details.reason;\n\t\tthis.path = details.path;\n\t\tthis.canonicalKey = details.canonicalKey;\n\t\tthis.requester = details.requester;\n\t\tthis.presentedTag = details.presentedTag;\n\t\tthis.evidence = details.evidence;\n\t\tthis.liveState = details.liveState;\n\t\tthis.causeCode = details.causeCode;\n\t}\n\n\t/**\n\t * Ordered by what must survive truncation: the code first, then the reason and guidance,\n\t * then the divergence, and the live-state summary last. The tail is the most expendable\n\t * because it is the part a reader can always recover by opening the file.\n\t */\n\tstatic formatMessage(details: FileMutationConflictDetails): string {\n\t\tconst tag = details.presentedTag ? ` (presented #${details.presentedTag})` : \"\";\n\t\tconst copy = REASON_COPY[details.reason];\n\t\tconst cause = details.causeCode ? ` (${details.causeCode})` : \"\";\n\t\treturn (\n\t\t\t`${FILE_MUTATION_CONFLICT_CODE}:${details.reason} ${details.path}${tag}: ` +\n\t\t\t`${copy.diagnosis}${cause}.${describeRequester(details.requester)} ` +\n\t\t\tcopy.instruction +\n\t\t\tdescribeEvidence(details.evidence) +\n\t\t\tdescribeLiveState(details.liveState)\n\t\t);\n\t}\n}\n\n/** Whether a thrown value is an exclusive-create collision reported by the filesystem. */\nexport function isExclusiveCreateCollision(error: unknown): boolean {\n\treturn typeof error === \"object\" && error !== null && \"code\" in error && error.code === \"EEXIST\";\n}\n\n/**\n * Whether a thrown value says the target is gone. `ENOTDIR` counts because a parent directory\n * replaced by a file makes the path unreachable for the same reason a deletion does.\n */\nexport function isMissingTargetError(error: unknown): boolean {\n\tconst code = filesystemErrorCode(error);\n\treturn code === \"ENOENT\" || code === \"ENOTDIR\";\n}\n\n/** The `code` a filesystem rejection carries, when it carries one. */\nexport function filesystemErrorCode(error: unknown): string | undefined {\n\tif (typeof error !== \"object\" || error === null || !(\"code\" in error)) return undefined;\n\tconst code = (error as { code?: unknown }).code;\n\treturn typeof code === \"string\" ? code : undefined;\n}\n\n/**\n * Guard for the window between preparing a mutation and committing it, called under the\n * mutation queue.\n *\n * `prepared` is the content the mutation was computed against, which for a hashline edit is\n * the file as `prepare` read it, NOT what the session originally observed, since `prepare`\n * re-reads and may have recovered onto drifted content. Naming that honestly matters: this\n * closes a time-of-check window, it does not prove the session read the file.\n *\n * Full text rather than tags: a hashline tag is 16 bits and the engine documents that it can\n * collide, so it is a label for the model to recognize, never proof of identity.\n */\nexport function assertLiveMatchesPrepared(args: {\n\treadonly canonicalKey: string;\n\treadonly path: string;\n\treadonly prepared: string;\n\treadonly live: string;\n\treadonly requester?: MutationRequester;\n\treadonly presentedTag?: string;\n}): void {\n\tif (args.live === args.prepared) return;\n\tconst evidence = computeConflictEvidence(args.prepared, args.live);\n\tthrow new FileMutationConflict({\n\t\treason: \"changed_before_write\",\n\t\tpath: args.path,\n\t\tcanonicalKey: args.canonicalKey,\n\t\trequester: args.requester,\n\t\tpresentedTag: args.presentedTag,\n\t\tliveState: computeLiveState(args.live),\n\t\t...(evidence ? { evidence } : {}),\n\t});\n}\n\n/**\n * Guard for `write` overwriting an existing file: this session must already have observed the\n * exact content it is about to replace.\n *\n * Asks the session's own store and never another session's, which is what keeps cross-session\n * rejection strict. `byHashAndText` answers both halves of the requirement at once, since a\n * hit means this session recorded exactly this content for this path.\n *\n * `storeKey` is the snapshot store's own key convention, the normalized absolute path, which\n * is NOT symlink-resolved unlike `canonicalKey`. Passing the wrong one makes a symlinked path\n * miss and report a false `no_prior_observation`.\n *\n * The tag is derived here rather than accepted. Unlike the engine's own use of\n * `byHashAndText`, where the hash is the independent claim a section presented, `write` has no\n * presented tag: it replaces the whole file. Any tag is therefore just `live` hashed, and\n * taking it as a parameter only creates a way for the two to disagree silently.\n */\nexport function assertPriorSessionObservation(args: {\n\treadonly canonicalKey: string;\n\treadonly storeKey: string;\n\treadonly path: string;\n\treadonly store: SnapshotStore;\n\treadonly live: string;\n\treadonly requester?: MutationRequester;\n}): void {\n\tif (args.store.byHashAndText(args.storeKey, computeFileHash(args.live), args.live)) return;\n\t// The last version this session recorded is what it believed it was overwriting, so the\n\t// divergence from live is the evidence. Without one there is nothing to diff, but the live\n\t// state still reports what was about to be clobbered sight unseen, which is the part\n\t// whoever reviews the rejection actually needs.\n\tconst head = args.store.head(args.storeKey);\n\tconst evidence = head ? computeConflictEvidence(head.text, args.live) : undefined;\n\tthrow new FileMutationConflict({\n\t\treason: head ? \"changed_since_observation\" : \"no_prior_observation\",\n\t\tpath: args.path,\n\t\tcanonicalKey: args.canonicalKey,\n\t\trequester: args.requester,\n\t\tliveState: computeLiveState(args.live),\n\t\t...(evidence ? { evidence } : {}),\n\t});\n}\n\n/**\n * Build a requester from parts already present on a session. Kept pure so it is testable\n * without constructing an `AgentSession`, and so this module never imports one.\n */\nexport function buildMutationRequester(parts: {\n\treadonly sessionId: string;\n\treadonly orchestration?: {\n\t\treadonly kind: string;\n\t\treadonly workflowRunId: string;\n\t\treadonly workflowStageId: string;\n\t\treadonly workflowStageName: string;\n\t};\n\treadonly intercom?: {\n\t\treadonly runId: string;\n\t\treadonly agent: string;\n\t\treadonly index?: number;\n\t\treadonly supervisor?: { readonly supervisorSessionId: string };\n\t};\n\treadonly attemptId?: string;\n\treadonly toolCallId?: string;\n}): MutationRequester {\n\tconst workflow = parts.orchestration?.kind === \"workflow-stage\" ? parts.orchestration : undefined;\n\tconst supervisorSessionId = parts.intercom?.supervisor?.supervisorSessionId;\n\tconst subagentIndex = parts.intercom?.index;\n\treturn {\n\t\tsessionId: parts.sessionId,\n\t\t...(supervisorSessionId ? { parentSessionId: supervisorSessionId } : {}),\n\t\t...(workflow ? { workflowRunId: workflow.workflowRunId } : {}),\n\t\t...(workflow ? { workflowStageId: workflow.workflowStageId } : {}),\n\t\t...(workflow ? { workflowStageName: workflow.workflowStageName } : {}),\n\t\t...(parts.intercom ? { subagentRunId: parts.intercom.runId } : {}),\n\t\t...(parts.intercom ? { subagentAgent: parts.intercom.agent } : {}),\n\t\t// Presence, not truthiness: index 0 is the first child, and `0 ? … : {}` drops it.\n\t\t...(subagentIndex !== undefined ? { subagentIndex } : {}),\n\t\t...(parts.attemptId ? { attemptId: parts.attemptId } : {}),\n\t\t...(parts.toolCallId ? { toolCallId: parts.toolCallId } : {}),\n\t};\n}\n"]}