@edspencer/paddock 0.0.1 → 0.56.0

package/packages/server/dist/management-policy.js

@@ -0,0 +1,259 @@
+/**
+ * Management API policy primitives (issue #312 M1).
+ *
+ * The `ManagementPrincipal` (WHO is calling) + `ManagementScope` (WHAT they may
+ * reach) and the pure predicates that decide a single call. This module is
+ * deliberately transport-free and dependency-free: it knows nothing about MCP,
+ * HTTP, Fastify or the ops callbacks. Everything here is a pure function over
+ * plain data, so the security-critical decisions are unit-testable without a
+ * fleet, a socket, or a server.
+ *
+ * ── Why policy lives HERE and not in the MCP transport ──────────────────────
+ * The ticket's central structural decision: enforcement happens at the OPS
+ * layer, not in whichever transport happens to be calling. Paddock will grow a
+ * REST surface for the same turn-spawning operations (#465); if policy lived in
+ * the MCP handler, REST would have to reimplement it and the two would drift.
+ * So the transports authenticate (producing a principal) and the ops layer
+ * enforces (consuming one) — see management-ops.ts.
+ *
+ * ── The blast-radius framing that drives the defaults ───────────────────────
+ * `create_chat` / `send_message` / `fork_chat*` / `run_trigger` START KEEPER
+ * TURNS, and a keeper runs with Bash + Write. So **any write scope is
+ * effectively remote code execution on the host.** Read-only is therefore the
+ * default for a configured client, writes are opt-in per client, and the
+ * grammar below is deny-biased at every ambiguity: deny beats allow, an unknown
+ * operation is denied, and an empty allow-list grants nothing.
+ */
+// ── The operation catalogue ────────────────────────────────────────────────
+// The canonical names policy is written against. These deliberately match the
+// self-MCP tool names one-for-one, so an operator writing `allow: ["read_chat"]`
+// names the same thing the agent sees as `mcp__paddock_manage__read_chat`, and
+// so a future REST route can reuse the identifier unchanged.
+/** Read-only operations: no state change, no turn started. */
+export const READ_OPERATIONS = ["list_projects", "list_chats", "read_chat"];
+/** Chat write operations. The first four START TURNS (see the RCE note above). */
+export const WRITE_OPERATIONS = [
+    "create_project",
+    "create_chat",
+    "fork_chat",
+    "send_message",
+    "fork_chat_batch",
+    "archive_chat",
+    "unarchive_chat",
+];
+/** Unified trigger operations (Epic T / T3). `list_triggers` is the read one. */
+export const TRIGGER_OPERATIONS = [
+    "list_triggers",
+    "set_trigger",
+    "remove_trigger",
+    "run_trigger",
+];
+/** Every operation the management surface knows about. */
+export const ALL_OPERATIONS = [
+    ...READ_OPERATIONS,
+    ...WRITE_OPERATIONS,
+    ...TRIGGER_OPERATIONS,
+];
+/**
+ * Operations that cause a keeper turn to run — directly (`create_chat`,
+ * `send_message`, `fork_chat*`, `run_trigger`) or by arming something that will
+ * (`set_trigger`). Granting ANY of these to a principal is granting code
+ * execution on the host; kept as an explicit set so that fact stays greppable
+ * and so docs/UI can warn on it.
+ */
+/**
+ * Operations that grant code execution on the host, and so define the risk class
+ * a write scope really is. A superset of {@link TURN_SPAWNING_OPERATIONS}:
+ * `create_project` starts no turn, but it clones a CALLER-SUPPLIED git URL and
+ * creates instance-level state, which belongs in the same warning.
+ */
+export const HIGH_RISK_OPERATIONS = [
+    "create_project",
+    "create_chat",
+    "fork_chat",
+    "fork_chat_batch",
+    "send_message",
+    "run_trigger",
+    "set_trigger",
+];
+export const TURN_SPAWNING_OPERATIONS = [
+    "create_chat",
+    "fork_chat",
+    "send_message",
+    "fork_chat_batch",
+    "run_trigger",
+    "set_trigger",
+];
+/**
+ * The DEFAULT scope for a configured client that specifies none — read-only
+ * across all projects. Matches the shape written on issue #312 verbatim
+ * (`allow: ["list_*", "read_chat"]`), which covers the three read tools plus
+ * `list_triggers` while excluding every mutating verb.
+ */
+export const DEFAULT_READ_ONLY_SCOPE = Object.freeze({
+    projects: ["*"],
+    allow: ["list_*", "read_chat"],
+    deny: [],
+});
+/** Unrestricted scope — used ONLY for the in-process keeper principal. */
+export const FULL_SCOPE = Object.freeze({
+    projects: ["*"],
+    allow: ["*"],
+    deny: [],
+});
+/**
+ * The implicit full-trust principal for the in-process keeper path.
+ *
+ * The internal caller is bounded by DEPTH (`maxSpawnDepth`, shipped in #278),
+ * not by auth+scope — it has no credential because it isn't a distinct identity.
+ * Handing it a full scope keeps a single enforcement path (every op checks a
+ * principal) while guaranteeing the keeper behaviour is byte-for-byte unchanged:
+ * every check below short-circuits to allow.
+ */
+export const INTERNAL_PRINCIPAL = Object.freeze({
+    clientId: "internal",
+    kind: "internal",
+    scope: FULL_SCOPE,
+});
+/** True for the implicit in-process principal (bounded by depth, not scope). */
+export function isInternalPrincipal(principal) {
+    return principal.kind === "internal";
+}
+/**
+ * Match one pattern against one value. Supports exactly two forms — a bare `"*"`
+ * (everything) and a trailing-`*` prefix (`"list_*"`) — plus exact equality.
+ *
+ * Deliberately NOT a general glob: a security predicate should be trivially
+ * auditable by the operator writing it, and the ticket calls for starting with
+ * explicit lists and adding globs only as needed. Anything fancier (`?`, `[]`,
+ * embedded `*`) is treated as a literal, so a typo'd pattern fails CLOSED
+ * (matches nothing) rather than accidentally widening a grant.
+ */
+export function matchesPattern(pattern, value) {
+    if (pattern === "*")
+        return true;
+    if (pattern.endsWith("*") && !pattern.slice(0, -1).includes("*")) {
+        return value.startsWith(pattern.slice(0, -1));
+    }
+    return pattern === value;
+}
+function matchesAny(patterns, value) {
+    return (patterns ?? []).some((p) => matchesPattern(p, value));
+}
+/**
+ * Whether `scope` permits invoking `operation`. Deny beats allow; an operation
+ * outside {@link ALL_OPERATIONS} is refused regardless of the allow-list, so a
+ * typo in config (or a tool added later that policy hasn't been taught about)
+ * can never be reached through a stale `"*"` grant.
+ */
+export function isOperationAllowed(scope, operation) {
+    if (!ALL_OPERATIONS.includes(operation))
+        return false;
+    if (matchesAny(scope.deny, operation))
+        return false;
+    return matchesAny(scope.allow, operation);
+}
+/** Whether `scope` permits touching `projectSlug`. Deny beats allow. */
+export function isProjectAllowed(scope, projectSlug) {
+    if (matchesAny(scope.denyProjects, projectSlug))
+        return false;
+    return matchesAny(scope.projects, projectSlug);
+}
+/** The concrete operations `scope` grants, in catalogue order. */
+export function allowedOperations(scope) {
+    return ALL_OPERATIONS.filter((op) => isOperationAllowed(scope, op));
+}
+/** True when `scope` grants at least one operation that starts a keeper turn. */
+export function grantsTurnSpawning(scope) {
+    return TURN_SPAWNING_OPERATIONS.some((op) => isOperationAllowed(scope, op));
+}
+// ── OAuth scope vocabulary ─────────────────────────────────────────────────
+// Two DIFFERENT granularities, deliberately:
+//
+//   - Internally, a scope is a list of OPERATION names. That is the right
+//     granularity for an operator writing a config file, who wants to say
+//     exactly which verbs a CI token may call.
+//   - Over OAuth, scopes are coarse (`paddock:read` / `paddock:write`), because
+//     they are shown to a HUMAN on a consent screen. "Grant this app
+//     create_chat, fork_chat, fork_chat_batch, send_message…" is not a consent
+//     prompt anyone reads; "grant write access" is.
+//
+// So the coarse names are a projection of the fine-grained truth, used only in
+// the `scope` parameter of a challenge and in the discovery document. Authorization
+// is always decided on the fine-grained list.
+export const OAUTH_SCOPE_READ = "paddock:read";
+export const OAUTH_SCOPE_WRITE = "paddock:write";
+/** Every OAuth scope this resource server understands (for discovery). */
+export const OAUTH_SCOPES_SUPPORTED = [OAUTH_SCOPE_READ, OAUTH_SCOPE_WRITE];
+/**
+ * The coarse OAuth scope an operation needs. Anything that mutates state or
+ * starts a turn is `write`; everything else is `read`.
+ */
+export function requiredOauthScope(operation) {
+    if (READ_OPERATIONS.includes(operation)) {
+        return OAUTH_SCOPE_READ;
+    }
+    return operation === "list_triggers" ? OAUTH_SCOPE_READ : OAUTH_SCOPE_WRITE;
+}
+/** The coarse OAuth scopes a fine-grained scope amounts to. */
+export function oauthScopesFor(scope) {
+    const out = [];
+    if (ALL_OPERATIONS.some((op) => isOperationAllowed(scope, op) && requiredOauthScope(op) === OAUTH_SCOPE_READ)) {
+        out.push(OAUTH_SCOPE_READ);
+    }
+    if (ALL_OPERATIONS.some((op) => isOperationAllowed(scope, op) && requiredOauthScope(op) === OAUTH_SCOPE_WRITE)) {
+        out.push(OAUTH_SCOPE_WRITE);
+    }
+    return out;
+}
+/** True when `scope` grants any operation that amounts to code execution. */
+export function grantsCodeExecution(scope) {
+    return HIGH_RISK_OPERATIONS.some((op) => isOperationAllowed(scope, op));
+}
+/**
+ * Thrown when policy refuses a call. Carries the structured facts a transport
+ * needs to render its own error (MCP `isError` text, or an HTTP 403) and that
+ * the server log wants — `clientId` + `operation`, never the credential.
+ */
+export class ManagementDeniedError extends Error {
+    code;
+    clientId;
+    operation;
+    projectSlug;
+    constructor(args) {
+        super(args.code === "operation_denied"
+            ? `not permitted: operation "${args.operation}" is outside this client's scope`
+            : `not permitted: project "${args.projectSlug}" is outside this client's scope`);
+        this.name = "ManagementDeniedError";
+        this.code = args.code;
+        this.clientId = args.clientId;
+        this.operation = args.operation;
+        this.projectSlug = args.projectSlug;
+    }
+}
+/** Throw unless `principal` may invoke `operation`. */
+export function assertOperation(principal, operation) {
+    if (!isOperationAllowed(principal.scope, operation)) {
+        throw new ManagementDeniedError({
+            code: "operation_denied",
+            clientId: principal.clientId,
+            operation,
+        });
+    }
+}
+/**
+ * Throw unless `principal` may reach `projectSlug` via `operation`. Callers that
+ * ENUMERATE (list_projects/list_chats) must filter with {@link isProjectAllowed}
+ * instead — a scoped client listing its two projects should see those two, not a
+ * denial. This assert is for calls that name a target explicitly.
+ */
+export function assertProject(principal, operation, projectSlug) {
+    if (!isProjectAllowed(principal.scope, projectSlug)) {
+        throw new ManagementDeniedError({
+            code: "project_denied",
+            clientId: principal.clientId,
+            operation,
+            projectSlug,
+        });
+    }
+}

package/packages/server/dist/message-provenance.d.ts

@@ -0,0 +1,112 @@
+/**
+ * WHO caused a machine-injected turn. A human-typed message carries NO sender
+ * (absence = human, the quiet default), so this type only enumerates the machine
+ * sources. Mirrors the web's `MessageSender` (packages/web/src/lib/types.ts).
+ *
+ *  - `chat`     — another chat `send_message`d / forked / created this turn; carries
+ *                 the sending chat's project + sessionId (for a deep link) + the
+ *                 display name it had at injection time.
+ *  - `schedule` — a schedule fire injected it; carries the schedule's name.
+ *  - `hook`     — an event hook fired it (Epic G / G1); carries the hook's name (and
+ *                 project) so a hook chat's kickoff turn is attributable.
+ *  - `recovery` — Paddock's keeper-chat recovery nudged this turn (issue #301):
+ *                 a human clicked "Continue" on a killed-background-task
+ *                 affordance (Layer 2), or Layer 3 auto re-drove the hung keeper.
+ *  - `agent`    — a machine turn with no more specific identity (fallback).
+ */
+export type MessageSender = {
+    kind: "chat";
+    project: string;
+    sessionId: string;
+    name?: string;
+} | {
+    kind: "schedule";
+    name: string;
+    project?: string;
+} | {
+    kind: "hook";
+    name: string;
+    project?: string;
+} | {
+    kind: "recovery";
+} | {
+    kind: "agent";
+};
+/** One recorded injection: its sender + the (possibly truncated) injected content. */
+export interface InjectedMarker {
+    sender: MessageSender;
+    /** The injected prompt, trimmed and capped to {@link MAX_CONTENT}. */
+    content: string;
+    /** True when `content` was capped — the join then prefix-matches instead of ==. */
+    truncated?: boolean;
+}
+export declare class MessageProvenanceStore {
+    private readonly stateFile;
+    /** In-memory map of sessionId -> ordered injection markers (loaded once, written through). */
+    private state;
+    /** The in-flight load, cached so concurrent first-callers share ONE read (see RunProvenanceStore). */
+    private loadPromise;
+    /** Serialises concurrent writes so the file never interleaves. */
+    private writing;
+    constructor(dataDir: string);
+    /** Load the persisted map (lazily, deduped; tolerant of a missing/corrupt file). */
+    private ensureLoaded;
+    /** This chat's ordered injection markers, or [] if none. Non-throwing. */
+    list(sessionId: string): Promise<InjectedMarker[]>;
+    /**
+     * The chat that most likely CREATED `sessionId` — the sender of its very FIRST
+     * injection marker, and only if that sender is a chat.
+     *
+     * This is a backfill, not a recorded fact. A chat spawned via `create_chat` /
+     * `fork_chat` gets its kickoff prompt injected BY the creating chat, so the
+     * first marker is the parent. Later markers are ordinary `send_message` traffic
+     * (any chat can message any other), which is why only the first one counts.
+     *
+     * That "only the first one counts" rule is POSITIONAL (#491). Scanning for the
+     * first `chat`-KIND marker instead — as this did originally, despite the doc
+     * comment — makes a chat whose creation was NOT a chat injection adopt whichever
+     * chat happens to message it first: a schedule-fired chat is re-parented under
+     * the child that reports back to it. So a non-chat first marker means "not
+     * created by a chat", and returns null rather than searching on.
+     *
+     * Newer chats carry a real, recorded edge on RunProvenance.parentSessionId;
+     * prefer that and fall back here for chats created before it existed. Returns
+     * null when the chat has no markers or was never injected into by a chat — that
+     * includes forks with no kickoff prompt, which record nothing at all.
+     *
+     * Pure in-memory read once loaded, so the chat list can call it per row.
+     */
+    parentChat(sessionId: string): Promise<{
+        project: string;
+        sessionId: string;
+        name?: string;
+    } | null>;
+    /**
+     * Append one injection marker for `sessionId`. Order is significant — the join
+     * consumes markers in the order they were recorded — so this only ever appends.
+     * A blank/unsafe session id or malformed sender is ignored (best effort; the
+     * turn still runs, it just won't be attributed).
+     */
+    record(sessionId: string, sender: MessageSender, content: string): Promise<void>;
+    /** Write-through, serialised so overlapping records can't corrupt the file. */
+    private persist;
+}
+/**
+ * Attach `sender` to each machine-injected user message by joining the parsed
+ * transcript against this session's ordered injection markers (issue #290).
+ *
+ * The join is greedy and in-order: a pointer walks the markers; for each plain
+ * user-text message we test it against the NEXT unconsumed marker, and on a match
+ * attach that sender and advance the pointer. A message that doesn't match the
+ * pending marker is treated as human-typed (left unlabelled) WITHOUT advancing the
+ * pointer, so a later injected message can still claim the marker. Order alignment
+ * holds because injections into a session are serialised and the transcript
+ * preserves order. Returns the input untouched when there are no markers.
+ */
+export declare function applyMessageProvenance<T extends {
+    role: string;
+    content: string;
+    toolCall?: unknown;
+}>(messages: T[], markers: InjectedMarker[]): (T & {
+    sender?: MessageSender;
+})[];

package/packages/server/dist/message-provenance.js

@@ -0,0 +1,260 @@
+/**
+ * MessageProvenanceStore — a Paddock-side sidecar recording WHO injected each
+ * machine-added turn into a chat's transcript (issue #290). This is the
+ * per-MESSAGE analog of {@link RunProvenanceStore} (A1/#261), which records how a
+ * whole CHAT was created. As chats reliably inject messages into one another —
+ * `send_message` (a spawned child reporting back), scheduled fires, spawned-chat
+ * kickoffs — a transcript can interleave turns a HUMAN typed with turns a MACHINE
+ * added, and in the UI they look identical. This store lets the web attribute the
+ * machine-added ones ("↩ sent by <chat>", "⏰ scheduled by <name>").
+ *
+ * WHY a content-keyed sidecar (not a per-message uuid map): the injected user
+ * turn's transcript `uuid` is minted by Claude Code when it writes the JSONL line,
+ * so Paddock never sees it at injection time. But Paddock DOES know the exact
+ * prompt string it injected, and that string lands verbatim as the user message's
+ * content. So we record, per target session, an ORDERED list of injection markers
+ * carrying the sender + the injected content; at DTO-build time we walk the parsed
+ * messages and greedily match each machine-injected user message to the next
+ * unconsumed marker (see {@link applyMessageProvenance}). Injections into one
+ * session are serialised (herdctl keeper concurrency + same-session resume), and
+ * the transcript preserves order, so the in-order join is stable. A human-typed
+ * message won't match a pending marker's content, so it stays unlabelled (the
+ * default).
+ *
+ * Shape + durability mirror the other sidecars exactly: a `sessionId ->
+ * InjectedMarker[]` map persisted as a plain JSON object, lazy-loaded (with the
+ * in-flight load promise cached so concurrent first-callers can't lose an update),
+ * write-through, serialised, corruption-tolerant, `0o600`.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+const STATE_FILE = "message-provenance.json";
+/**
+ * The longest injected-content prefix we persist per marker. Bounds sidecar size
+ * for a large `promptFile`-driven schedule while keeping ordinary short kickoffs
+ * matched exactly. Beyond this the match falls back to prefix equality (a full
+ * transcript content that STARTS WITH the stored prefix), which is unambiguous
+ * enough given the in-order consumption.
+ */
+const MAX_CONTENT = 8192;
+/** A session id we're willing to key on — mirrors RunProvenanceStore's guard. */
+function isSafeId(sessionId) {
+    return typeof sessionId === "string" && /^[A-Za-z0-9._-]+$/.test(sessionId);
+}
+const SENDER_KINDS = new Set(["chat", "schedule", "hook", "recovery", "agent"]);
+/** Validate + normalise an untrusted value into a MessageSender, or null. */
+function coerceSender(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const o = value;
+    if (typeof o.kind !== "string" || !SENDER_KINDS.has(o.kind))
+        return null;
+    if (o.kind === "chat") {
+        if (typeof o.project !== "string" || typeof o.sessionId !== "string")
+            return null;
+        return {
+            kind: "chat",
+            project: o.project,
+            sessionId: o.sessionId,
+            ...(typeof o.name === "string" ? { name: o.name } : {}),
+        };
+    }
+    if (o.kind === "schedule") {
+        if (typeof o.name !== "string")
+            return null;
+        return {
+            kind: "schedule",
+            name: o.name,
+            ...(typeof o.project === "string" ? { project: o.project } : {}),
+        };
+    }
+    if (o.kind === "hook") {
+        if (typeof o.name !== "string")
+            return null;
+        return {
+            kind: "hook",
+            name: o.name,
+            ...(typeof o.project === "string" ? { project: o.project } : {}),
+        };
+    }
+    if (o.kind === "recovery")
+        return { kind: "recovery" };
+    return { kind: "agent" };
+}
+/** Validate + normalise an untrusted value into an InjectedMarker, or null. */
+function coerceMarker(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const o = value;
+    const sender = coerceSender(o.sender);
+    if (!sender)
+        return null;
+    if (typeof o.content !== "string")
+        return null;
+    return { sender, content: o.content, ...(o.truncated === true ? { truncated: true } : {}) };
+}
+/** Normalise + cap injected content for storage; also used at match time. */
+function normaliseContent(content) {
+    const trimmed = content.trim();
+    if (trimmed.length <= MAX_CONTENT)
+        return { content: trimmed, truncated: false };
+    return { content: trimmed.slice(0, MAX_CONTENT), truncated: true };
+}
+export class MessageProvenanceStore {
+    stateFile;
+    /** In-memory map of sessionId -> ordered injection markers (loaded once, written through). */
+    state = null;
+    /** The in-flight load, cached so concurrent first-callers share ONE read (see RunProvenanceStore). */
+    loadPromise = null;
+    /** Serialises concurrent writes so the file never interleaves. */
+    writing = Promise.resolve();
+    constructor(dataDir) {
+        this.stateFile = path.join(dataDir, STATE_FILE);
+    }
+    /** Load the persisted map (lazily, deduped; tolerant of a missing/corrupt file). */
+    ensureLoaded() {
+        if (this.state)
+            return Promise.resolve(this.state);
+        if (!this.loadPromise) {
+            this.loadPromise = (async () => {
+                const map = new Map();
+                try {
+                    const raw = await fs.readFile(this.stateFile, "utf8");
+                    const parsed = JSON.parse(raw);
+                    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                        for (const [k, v] of Object.entries(parsed)) {
+                            if (!Array.isArray(v))
+                                continue;
+                            const markers = v.map(coerceMarker).filter((m) => m !== null);
+                            if (markers.length)
+                                map.set(k, markers);
+                        }
+                    }
+                }
+                catch {
+                    /* missing or unreadable — start empty */
+                }
+                this.state = map;
+                return map;
+            })();
+        }
+        return this.loadPromise;
+    }
+    /** This chat's ordered injection markers, or [] if none. Non-throwing. */
+    async list(sessionId) {
+        if (!isSafeId(sessionId))
+            return [];
+        const map = await this.ensureLoaded().catch(() => new Map());
+        return map.get(sessionId) ?? [];
+    }
+    /**
+     * The chat that most likely CREATED `sessionId` — the sender of its very FIRST
+     * injection marker, and only if that sender is a chat.
+     *
+     * This is a backfill, not a recorded fact. A chat spawned via `create_chat` /
+     * `fork_chat` gets its kickoff prompt injected BY the creating chat, so the
+     * first marker is the parent. Later markers are ordinary `send_message` traffic
+     * (any chat can message any other), which is why only the first one counts.
+     *
+     * That "only the first one counts" rule is POSITIONAL (#491). Scanning for the
+     * first `chat`-KIND marker instead — as this did originally, despite the doc
+     * comment — makes a chat whose creation was NOT a chat injection adopt whichever
+     * chat happens to message it first: a schedule-fired chat is re-parented under
+     * the child that reports back to it. So a non-chat first marker means "not
+     * created by a chat", and returns null rather than searching on.
+     *
+     * Newer chats carry a real, recorded edge on RunProvenance.parentSessionId;
+     * prefer that and fall back here for chats created before it existed. Returns
+     * null when the chat has no markers or was never injected into by a chat — that
+     * includes forks with no kickoff prompt, which record nothing at all.
+     *
+     * Pure in-memory read once loaded, so the chat list can call it per row.
+     */
+    async parentChat(sessionId) {
+        const [first] = await this.list(sessionId);
+        if (first?.sender.kind !== "chat")
+            return null;
+        // Never let a corrupt record make a chat its own parent — buildChatTree
+        // guards cycles too, but a self-edge is meaningless this far up.
+        if (first.sender.sessionId === sessionId)
+            return null;
+        return {
+            project: first.sender.project,
+            sessionId: first.sender.sessionId,
+            ...(first.sender.name ? { name: first.sender.name } : {}),
+        };
+    }
+    /**
+     * Append one injection marker for `sessionId`. Order is significant — the join
+     * consumes markers in the order they were recorded — so this only ever appends.
+     * A blank/unsafe session id or malformed sender is ignored (best effort; the
+     * turn still runs, it just won't be attributed).
+     */
+    async record(sessionId, sender, content) {
+        if (!isSafeId(sessionId))
+            return;
+        const s = coerceSender(sender);
+        if (!s)
+            return;
+        const { content: capped, truncated } = normaliseContent(content);
+        const marker = { sender: s, content: capped, ...(truncated ? { truncated: true } : {}) };
+        const map = await this.ensureLoaded();
+        const list = map.get(sessionId);
+        if (list)
+            list.push(marker);
+        else
+            map.set(sessionId, [marker]);
+        await this.persist(map);
+    }
+    /** Write-through, serialised so overlapping records can't corrupt the file. */
+    persist(map) {
+        this.writing = this.writing.then(async () => {
+            const obj = {};
+            for (const [k, v] of map)
+                obj[k] = v;
+            const json = JSON.stringify(obj, null, 2);
+            await fs.writeFile(this.stateFile, json, { encoding: "utf8", mode: 0o600 }).catch(() => undefined);
+        });
+        return this.writing;
+    }
+}
+/** True when a message is a plain user text turn (a candidate injected turn). */
+function isPlainUserText(m) {
+    if (m.role !== "user" || m.toolCall)
+        return false;
+    // A background `<task-notification>` is a harness-injected user line, not a
+    // send_message/schedule injection — never attribute it to a sender.
+    return !m.content.trimStart().startsWith("<task-notification>");
+}
+/** Does a parsed message's content satisfy a marker (exact, or prefix if capped)? */
+function matchesMarker(content, marker) {
+    const trimmed = content.trim();
+    return marker.truncated ? trimmed.startsWith(marker.content) : trimmed === marker.content;
+}
+/**
+ * Attach `sender` to each machine-injected user message by joining the parsed
+ * transcript against this session's ordered injection markers (issue #290).
+ *
+ * The join is greedy and in-order: a pointer walks the markers; for each plain
+ * user-text message we test it against the NEXT unconsumed marker, and on a match
+ * attach that sender and advance the pointer. A message that doesn't match the
+ * pending marker is treated as human-typed (left unlabelled) WITHOUT advancing the
+ * pointer, so a later injected message can still claim the marker. Order alignment
+ * holds because injections into a session are serialised and the transcript
+ * preserves order. Returns the input untouched when there are no markers.
+ */
+export function applyMessageProvenance(messages, markers) {
+    if (markers.length === 0)
+        return messages;
+    let i = 0;
+    return messages.map((m) => {
+        if (i >= markers.length || !isPlainUserText(m))
+            return m;
+        if (matchesMarker(m.content, markers[i])) {
+            const sender = markers[i].sender;
+            i++;
+            return { ...m, sender };
+        }
+        return m;
+    });
+}