@intentic/sandbox-contract 1.248.0 → 1.249.0

package/src/model-roles.ts

@@ -1,320 +0,0 @@
-import { z } from "zod";
-
-/* EVERY JOB IN THIS SANDBOX THAT PICKS A MODEL, LISTED BY THE JOB IT IS, one row per answer the owner is
- * entitled to give differently.
- *
- * WHAT THIS REPLACED, and why it had to go. Model settings used to be grouped by how HARD the work was assumed
- * to be: a "quick model" for the small automatic jobs, an "agent runs" tier for the big ones. Both names
- * described an intensity rather than a job, and an intensity is a guess somebody else made about work the owner
- * knows better. A commit message written by a frontier model is not a mistake, it is a preference, and the
- * grouping made it unsayable: pinning Opus to get better commit subjects also pinned it to session titles, to
- * every loop verdict, and to the safety judge. One bundled row could not say the thing anyone actually wanted
- * to say.
- *
- * SO THE UNIT IS THE ROLE. Each entry here is one place a model gets chosen, and each gets its own ordered list
- * in settings.modelRoles. Seventeen rows is more than four, and that is the point rather than a cost being
- * absorbed: the configuration and the UI both already existed per use-case, and collapsing them was the only
- * thing standing between the owner and a choice the machinery could already honour. A simpler face over this
- * (presets: "cheap everywhere", "frontier everywhere") is a thing that can be built ON TOP of a true model, and
- * cannot be unpicked from a lossy one.
- *
- * EVERY LIST IS AN ORDERED LADDER, whatever the role, and for one reason: the interesting failure of a pinned
- * model is not that it is wrong, it is that it is CONNECTED AND WILL NOT ANSWER TODAY. The account's allowance
- * went on the chat this morning, and one spent provider takes the role down for hours while three others sit
- * idle. Written in order, the next entry catches it.
- *
- * AN EMPTY LIST IS THE JOB SWITCHED OFF, and NOTHING IS DERIVED FOR IT. A helper role used to fall to an
- * "Auto ladder" worked out from whatever was connected — every provider's cheapest row, best-first — so a
- * sandbox that had never been configured still spent somebody's account on commit messages and safety
- * verdicts, on a recommendation this table invented, which re-ranked itself the day another account was
- * connected. Not set now means not set: no auto-selection, no recommendation, and the owner names the models
- * for a job or the job does not happen.
- *
- * TWO KINDS, and what separates them is what the CALLER does with that empty answer. It is declared per role
- * because it is a property of the job:
- *
- *   helper — a one-shot. One prompt, no tools, one string back, and it is over. With no list the job does not
- *            run at all: no commit subject is drafted, no session is renamed, no command is judged. Every one
- *            of them already had a road for "the model could not answer" (the derived title stands, the
- *            commit box stays empty, the gate falls to its standing rule), so an owner who wants none of them
- *            leaves the row empty and pays nothing.
- *
- *   run    — a whole session with tools and a worktree, started by a surface rather than by a person at a
- *            composer. With no list the caller's own floor answers: the model the owner picked for their chat.
- *            That is not this table recommending anything — it is a choice they already made, in front of
- *            them, on the composer they work in.
- *
- * EVERY ENTRY IS A FULL PIN (ModelPinSchema): which model, and how it runs — effort, thinking, speed, harness.
- * The helper roles carry them too, which they did not use to: a one-shot ran with reasoning forcibly off, so
- * pinning a reasoning model to commit messages bought the price of one and the behaviour of neither. The knobs
- * now ride through the one-shot path (the daemon's role-model.ts), so an entry means what it says wherever it
- * is written.
- *
- * ADDING A ROLE IS ONE ROW HERE. The settings key, the resolver's floor, the daemon's lookup and the settings
- * page's row all read this table, so a job that starts picking a model tomorrow becomes configurable by saying
- * what it is. That is the property the old grouping cost: a new surface inherited "agent runs" by being
- * unattended, which is how a documentation sweep and a production incident came to share one tier. */
-
-export const ModelRoleKindSchema = z.enum(["helper", "run"]);
-export type ModelRoleKind = z.infer<typeof ModelRoleKindSchema>;
-
-/* WHAT STARTS A RUN, declared for the run roles alone.
- *
- * It is not a wire value and never has been: it decides which BLOCK a job is read in, and the argument for
- * reading them apart is the same one that separates a helper from a run — an owner holds a session nobody is
- * watching to a different budget from one they are sitting in front of. The settings page used to make that
- * argument in a comment over a thirteen-row list ("the ones somebody presses ahead of the ones that fire on
- * their own"), which is a claim no reader can check and no row has to honour. Declared, it draws the page.
- *
- * A HELPER DECLARES NONE, and that is the honest answer rather than a gap: nobody presses "write me a commit
- * subject". It happens because something else did. */
-export type ModelRoleTrigger = "pressed" | "unprompted";
-
-/* The shape of a row. `id` is a bare string HERE and narrowed on the exported type below, because the id union
- * is derived from this very table: a self-referential `satisfies` would be a type that has to know its own
- * answer before it can check it. */
-interface ModelRoleRow {
-    readonly id: string;
-    // What the settings row is called. A JOB, in the owner's words, never a tier.
-    readonly label: string;
-    // The row's one line: what this model is asked to do. Read beside the label, so it says what the label
-    // cannot rather than restating it.
-    readonly blurb: string;
-    readonly kind: ModelRoleKind;
-    /** Runs only, and required for every one of them: see `ModelRoleTrigger`. */
-    readonly trigger?: ModelRoleTrigger;
-    // The row's glyph, from the shared icon set. Here rather than in a web-side map because the whole value of
-    // this table is that a role is declared ONCE; a second table keyed by the same ids is the drift this
-    // replaced, moved one layer up.
-    readonly icon: string;
-}
-
-/* THE TABLE. Ordered as the settings page draws it, and the order is an argument about reach: the one-shots
- * first, because nobody chose a model for them and they run constantly; then the runs somebody's click starts;
- * then the runs that start themselves, which are the ones an owner is least likely to be watching and most
- * likely to want held to a budget. Those three are BLOCKS now (see MODEL_ROLE_BLOCKS) rather than an ordering
- * this comment asserts and nothing holds to.
- *
- * The ids are the wire vocabulary: a turn carries one (AgentTurn.runRole), so they are kebab-case and stable,
- * and renaming one is a breaking change to the setting rather than a cosmetic edit. */
-export const MODEL_ROLES = [
-    {
-        id: "commit-message",
-        label: "Commit messages",
-        blurb: "The subject written when an agent's work lands, and the release note under it.",
-        kind: "helper",
-        icon: "file-edit",
-    },
-    {
-        id: "session-title",
-        label: "Session titles",
-        blurb: "The name a conversation wears on the board, written a second into its first turn.",
-        kind: "helper",
-        icon: "pencil",
-    },
-    {
-        /* THE ONE HELPER WHOSE INPUT IS ADVERSARIAL, and the reason the old bundling was worst here. Its prompt
-         * contains a command the agent is about to run, which may have arrived from a stranger's web page, and a
-         * small model can be talked round by it. Being wrong is expensive in both directions: a needless card
-         * teaches the owner to click through the next one. */
-        id: "safety-judge",
-        label: "Safety judge",
-        blurb: "Which model reads your safety policy before a flagged command runs.",
-        kind: "helper",
-        icon: "shield",
-    },
-    {
-        id: "loop-verdict",
-        label: "Loop verdicts",
-        blurb: "Whether a loop's iteration met the goal, or the loop goes round again.",
-        kind: "helper",
-        icon: "check-square",
-    },
-    {
-        /* THE ONE HELPER THAT ANSWERS A CLASSIFICATION rather than writing prose: one card id, or none, from the
-         * owner's own short list (schemas/personas.ts `brief`). Cheap by construction, once per chat, and the
-         * job a small model does well, which is the whole argument for routing chats onto static cards rather
-         * than asking a model to compose a context per session. */
-        id: "persona-router",
-        label: "Persona routing",
-        blurb: "Which model reads a new chat's first message and picks the persona for it.",
-        kind: "helper",
-        icon: "users",
-    },
-    {
-        id: "pipeline-fix",
-        label: "Pipeline fixes",
-        blurb: "The agent started by Fix on a red pipeline.",
-        kind: "run",
-        trigger: "pressed",
-        icon: "wave-pulse",
-    },
-    {
-        id: "deployment-fix",
-        label: "Deployment fixes",
-        blurb: "The agent started by Fix on a deployment that is down.",
-        kind: "run",
-        trigger: "pressed",
-        icon: "server",
-    },
-    {
-        id: "maintenance-chore",
-        label: "Maintenance chores",
-        blurb: "A chore run started from the Maintenance board.",
-        kind: "run",
-        trigger: "pressed",
-        icon: "wrench",
-    },
-    {
-        id: "documentation-run",
-        label: "Documentation runs",
-        blurb: "A pass over a repo's own documentation.",
-        kind: "run",
-        trigger: "pressed",
-        icon: "book",
-    },
-    {
-        id: "acceptance-run",
-        label: "Acceptance runs",
-        blurb: "One session per story in an acceptance fan-out.",
-        kind: "run",
-        trigger: "pressed",
-        icon: "list-check",
-    },
-    {
-        id: "pre-push-fix",
-        label: "Pre-push fixes",
-        blurb: "The fix proposed when a check fails on the way to a push.",
-        kind: "run",
-        trigger: "pressed",
-        icon: "cloud-upload",
-    },
-    {
-        /* PRESSED, ON THE STRENGTH OF THE APPROVAL. Nothing here runs until somebody reads the item and says
-         * yes, and that press is the start of this turn as much as Fix is the start of a pipeline run — the
-         * queue between the two is machinery, not a second decision. */
-        id: "approval-queue",
-        label: "Approvals queue",
-        blurb: "The turn that publishes or acts on what you approved.",
-        kind: "run",
-        trigger: "pressed",
-        icon: "check-circle",
-    },
-    {
-        id: "automation-wake",
-        label: "Automation wakes",
-        blurb: "A turn an automation fires: a schedule, a webhook, a message from outside.",
-        kind: "run",
-        trigger: "unprompted",
-        icon: "clock",
-    },
-    {
-        id: "extension-review",
-        label: "Extension update reviews",
-        blurb: "The agent that reads an extension update before it is applied.",
-        kind: "run",
-        trigger: "unprompted",
-        icon: "box",
-    },
-    {
-        id: "loop-iteration",
-        label: "Loop iterations",
-        blurb: "Each round of a loop working towards its goal.",
-        kind: "run",
-        trigger: "unprompted",
-        icon: "repeat",
-    },
-    {
-        id: "watch-wake",
-        label: "Watch wakes",
-        blurb: "The turn a watch starts when the thing it was watching happens.",
-        kind: "run",
-        trigger: "unprompted",
-        icon: "eye",
-    },
-    {
-        id: "verify-nudge",
-        label: "Verify nudges",
-        blurb: "The follow-up turn sent when work was left unverified.",
-        kind: "run",
-        trigger: "unprompted",
-        icon: "search",
-    },
-    {
-        /* THE ONE ROLE THAT ANSWERS A CHOICE RATHER THAN FILLING A SILENCE. A spawning agent may name its
-         * child's provider, and when it does that wins, exactly as a caret pick wins on every other run role.
-         * This is what answers when it names none, which used to be a hardcoded "claude". */
-        id: "child-agent",
-        label: "Child agents",
-        blurb: "What an agent's own subagents run on when it names no model for them.",
-        kind: "run",
-        trigger: "unprompted",
-        icon: "users",
-    },
-] as const satisfies readonly ModelRoleRow[];
-
-export type ModelRole = (typeof MODEL_ROLES)[number]["id"];
-export type ModelRoleSpec = ModelRoleRow & { readonly id: ModelRole };
-
-export const MODEL_ROLE_IDS = MODEL_ROLES.map((role) => role.id) as readonly ModelRole[];
-
-/* The wire form. An enum rather than a string, unlike most ids in this contract, because there is no case for
- * an unknown one: a role is a place in THIS codebase where a model gets chosen, so a value outside the table
- * names nothing, and a settings file or a turn carrying one is a typo worth a clean error rather than a list
- * silently ignored. */
-export const ModelRoleSchema = z.enum(MODEL_ROLE_IDS as [ModelRole, ...ModelRole[]]);
-
-/* ═══ THE BLOCKS THE SETTINGS PAGE READS IN ═══
- *
- * EIGHTEEN JOBS IN ONE LIST IS A TABLE, NOT A PAGE. The unit being the role is right and is not in question —
- * it is what lets an owner pin Opus to commit subjects without pinning it to every session title — but the cost
- * lands on whoever opens the page: one unbroken run of eighteen rows, each with a name, a sentence, a control
- * and a list under it, with no landmark to say where you are in it or which rows are like the one you came for.
- *
- * SO THE BLOCKS ARE DECLARED, AND THEY ARE THE DISTINCTIONS THE TABLE ALREADY MAKES. Nothing here is a fresh
- * taxonomy invented for the layout: `kind` was always the difference between a one-shot and a whole session,
- * and `trigger` is the sentence the old table wrote in a comment about its own ordering. A block is what those
- * two answers already separate, given a name and a heading.
- *
- * THE LABELS LIVE HERE, beside the role labels, for the same reason those do: a heading kept in a web-side map
- * keyed by the same ids is the drift a single table exists to stop. What is NOT here is anything about how the
- * page draws them — that is the page's, and it changes on its own schedule.
- *
- * ORDER IS REACH, and it is the order of the table itself: jobs nobody picked a model for, then sessions a
- * click of yours starts, then sessions that start without one. Every role belongs to exactly one block and
- * every block keeps the table's order, which is what makes a role added upstairs appear on the page by
- * existing. */
-export type ModelRoleBlockId = "helper" | "pressed" | "unprompted";
-
-export interface ModelRoleBlock {
-    readonly id: ModelRoleBlockId;
-    /** The group's heading on the settings page. */
-    readonly label: string;
-    /** One line beside it: what the jobs in this block have in common that the others do not. */
-    readonly caption: string;
-    /** Its roles, in table order. */
-    readonly roles: readonly ModelRoleSpec[];
-}
-
-const rolesWhere = (match: (role: ModelRoleSpec) => boolean): readonly ModelRoleSpec[] => MODEL_ROLES.filter((role) => match(role));
-
-export const MODEL_ROLE_BLOCKS: readonly ModelRoleBlock[] = [
-    {
-        id: "helper",
-        label: "Automatic helpers",
-        caption: "One prompt, no tools, one answer back.",
-        roles: rolesWhere((role) => role.kind === "helper"),
-    },
-    {
-        id: "pressed",
-        label: "Runs you start",
-        caption: "Whole sessions, begun by a click of yours.",
-        roles: rolesWhere((role) => role.kind === "run" && role.trigger === "pressed"),
-    },
-    {
-        id: "unprompted",
-        label: "Runs that start themselves",
-        caption: "Whole sessions nobody pressed for.",
-        roles: rolesWhere((role) => role.kind === "run" && role.trigger === "unprompted"),
-    },
-];

package/src/needs-action.ts

@@ -1,14 +0,0 @@
-import { z } from "zod";
-
-/* ONE "DO THIS BY HAND" LINE, the honesty unit three surfaces share: what an arrival could not do for the
- * owner (arrival.ts), what a derived definition could not express (definition.ts), and where a runner has
- * drifted from its parent (runner-protocol.ts). A subject the UI bolds, a detail written as an instruction.
- *
- * It lives in its own leaf module because runner-protocol.ts speaks it, and THAT file is imported by
- * schemas/agent.ts, which definition.ts imports — the schema living in definition.ts made a cycle that left
- * schemas half-initialized under module-eval.
- *
- * The name says the FIELD it fills (`needsAction`) rather than any one surface, because naming it for the
- * definition is what let the arrival surfaces drift apart in the first place. */
-export const NeedsActionSchema = z.object({ subject: z.string(), detail: z.string() });
-export type NeedsAction = z.infer<typeof NeedsActionSchema>;

package/src/output-fields.ts

@@ -1,111 +0,0 @@
-import { z } from "zod";
-
-/* A DECLARED OUTPUT SHAPE, the answer to "what does this session produce?", written once and used three ways.
- *
- * An agentic session's natural output is prose, and prose is unusable as an input to the next session: a step
- * that must hand "the three files worth changing" to the step after it cannot hand over a paragraph that
- * mentions them. So a session that feeds another one declares its shape here, and that one declaration
- * becomes: the sentence in the prompt that tells the model what to write, the validator that decides whether
- * it complied, and the table the run view renders. Written once because the three drift apart the moment they
- * are written twice, a prompt asking for `files` and a validator wanting `paths` fails on every iteration and
- * says nothing useful about why.
- *
- * WHY A FIELD LIST AND NOT JSON SCHEMA. JSON Schema is strictly more expressive and completely unauthorable in
- * a form: nobody designing a workflow is going to hand-write `{"type":"object","properties":{...}}`, and a UI
- * that generates it becomes a schema editor, which is a product of its own. Four scalar types plus a string
- * list covers what one session actually hands another, a verdict, a count, a list of paths, a summary, and
- * anything past that is better carried as a file the next step reads.
- *
- * `description` IS REQUIRED, and that is the field that decides whether this works at all. `{name: "risk"}`
- * gets you the model's guess at what risk means; `{name: "risk", description: "high | medium | low, how
- * likely this change is to break something at runtime"}` gets you the answer to the question you asked.
- */
-
-// Restricted to a JS-identifier-ish shape: these become object keys the prompt spells out literally, and a
-// name with a quote or a newline in it produces a prompt that cannot be complied with.
-const FIELD_NAME = /^[a-zA-Z_][a-zA-Z0-9_]{0,39}$/;
-
-export const OutputFieldSchema = z.object({
-    name: z.string().regex(FIELD_NAME),
-    type: z.enum(["string", "number", "boolean", "string[]"]),
-    // What the field means, in the words the model is given. Not optional, see the note above.
-    description: z.string().min(1),
-    // An absent optional field validates; an absent required one does not, and the iteration is told which.
-    required: z.boolean(),
-});
-export type OutputField = z.infer<typeof OutputFieldSchema>;
-
-// How many fields one output may declare. A shape past this is not a handoff, it is a report, and a report is
-// what the prose half of the document is for.
-export const OUTPUT_FIELDS_MAX = 16;
-
-/* Repeated names make the declaration internally contradictory: object validation can only keep one rule for
- * a key, while a consumer looking the field up sees whichever copy it happens to ask for first. Reject them at
- * the declaration boundary, before either interpretation gets a chance to exist. Exported because graph-level
- * validation uses the same fact to explain the fault in the designer before a save is attempted. */
-export const duplicateOutputFieldNames = (fields: readonly Pick<OutputField, "name">[]): string[] => {
-    const seen = new Set<string>();
-    const repeated = new Set<string>();
-    for (const field of fields) {
-        if (seen.has(field.name)) {
-            repeated.add(field.name);
-        }
-        seen.add(field.name);
-    }
-    return [...repeated];
-};
-
-export const OutputFieldsSchema = z
-    .array(OutputFieldSchema)
-    .min(1)
-    .max(OUTPUT_FIELDS_MAX)
-    .superRefine((fields, context) => {
-        for (const name of duplicateOutputFieldNames(fields)) {
-            context.addIssue({ code: "custom", message: `Output field names must be unique; "${name}" is repeated.` });
-        }
-    });
-
-const validatorFor = (field: OutputField): z.ZodType => {
-    if (field.type === "number") {
-        return z.number();
-    }
-    if (field.type === "boolean") {
-        return z.boolean();
-    }
-    if (field.type === "string[]") {
-        return z.array(z.string());
-    }
-    return z.string();
-};
-
-/* The declared shape as a validator. Unknown keys are ALLOWED THROUGH: a model that answered everything asked
- * of it and then added a `notes` key has complied, and failing it there would burn an iteration teaching it to
- * write less. What is enforced is that every required field is present and every present field has the
- * declared type, the two things the reader downstream is entitled to assume.
- */
-export const fieldsValidator = (fields: readonly OutputField[]): z.ZodType =>
-    z.looseObject(Object.fromEntries(fields.map((field) => [field.name, field.required ? validatorFor(field) : validatorFor(field).optional()])));
-
-// A worked example of the declared shape, so the prompt can show rather than describe. Values are the field's
-// own description, a model copying the example's structure has the description in front of it as it fills each
-// slot, which is where it is needed rather than in a legend three lines up.
-export const fieldsExample = (fields: readonly OutputField[]): Record<string, unknown> =>
-    Object.fromEntries(
-        fields.map((field) => {
-            const hint = `${field.description}${field.required ? "" : " (optional, omit if it does not apply)"}`;
-            if (field.type === "number") {
-                return [field.name, 0];
-            }
-            if (field.type === "boolean") {
-                return [field.name, false];
-            }
-            if (field.type === "string[]") {
-                return [field.name, [hint]];
-            }
-            return [field.name, hint];
-        }),
-    );
-
-// One line per field, for surfaces with no room to render an example: "risk (string, required), how likely …".
-export const describeFields = (fields: readonly OutputField[]): string =>
-    fields.map((field) => `- \`${field.name}\` (${field.type}${field.required ? ", required" : ", optional"}), ${field.description}`).join(`\n`);

package/src/overlay-lint.ts

@@ -1,116 +0,0 @@
-/* WHAT AN ENVIRONMENT OVERLAY MAY SAY, read the same way by everyone who handles one.
- *
- * An overlay is the Dockerfile that extends the sandbox image for one sandbox: a pinned FROM, the enabled
- * capabilities' fragments, and the custom section the owner approved. Three readers apply the same grammar
- * at three trust levels, and none of them may trust the one before:
- *   • the daemon admits an EXTENSION's fragment only if it is RUN/ENV (capabilities/handlers/extension.ts at
- *     install, environment/fragment-sources.ts again at compose, in case the checkout changed);
- *   • the daemon pins the composed file's first instruction to the official image (environment.ts);
- *   • the platform builds a HOSTED sandbox's overlay on a machine of its own, from content that reached it
- *     through an agent-writable volume and a browser, so it re-checks all of it before any machine exists.
- * Text in, verdict out. No filesystem and no services, so the platform imports this the way it imports
- * tunnel-ids, and the ic binary's Rust twin (recreate.rs `overlay_base`, runner.rs) reads the same shape. */
-
-// The marker the rebuild executors read runtime privileges from (`# intentic:runtime --privileged`, the
-// docker run flag it becomes is allowlisted there). A fragment that can be written by anything but the
-// daemon's own code must not carry it, in a comment or anywhere else.
-const RUNTIME_DIRECTIVE = "intentic:runtime";
-
-const OFFICIAL_SANDBOX_IMAGE = /^ghcr\.io\/intentic\/sandbox:\S+$/;
-
-// The published sandbox image under any tag, the only base an overlay may extend.
-export const isOfficialSandboxImage = (ref: string): boolean => OFFICIAL_SANDBOX_IMAGE.test(ref);
-
-interface OverlayLine {
-    readonly raw: string;
-    // `body` is a line inside a `\`-continued instruction, which carries no keyword of its own.
-    readonly kind: "blank" | "comment" | "instruction" | "body";
-}
-
-// Continuation-aware: a `\` at the end of any line, comments included, makes the next line a body line.
-const overlayLines = (content: string): OverlayLine[] => {
-    let continued = false;
-    return content.split("\n").map((raw) => {
-        const line = raw.trim();
-        const wasContinued = continued;
-        continued = line.endsWith("\\");
-        const kind = line === "" ? "blank" : line.startsWith("#") ? "comment" : wasContinued ? "body" : "instruction";
-        return { raw, kind };
-    });
-};
-
-const FROM = /^from\s+(\S+)/i;
-const RUN_OR_ENV = /^(run|env)\s/i;
-
-/* An extension fragment may install and set variables, and nothing else. FROM is refused because the daemon
- * owns the base pin; every other instruction because there is no build context to COPY from and nothing an
- * extension has any business doing to USER, ENTRYPOINT or EXPOSE; and the runtime directive anywhere,
- * because an out-of-band executor greps for it and a comment is exactly where it would hide. Answers the
- * offending line, or undefined when the fragment is clean. */
-export const invalidExtensionFragment = (content: string): string | undefined => {
-    for (const { raw, kind } of overlayLines(content)) {
-        if (raw.includes(RUNTIME_DIRECTIVE)) {
-            return raw;
-        }
-        if (kind === "instruction" && !RUN_OR_ENV.test(raw.trim())) {
-            return raw;
-        }
-    }
-    return undefined;
-};
-
-// The image a composed overlay extends: the first instruction, when it is a FROM.
-export const overlayBase = (content: string): string | undefined => {
-    const first = overlayLines(content).find((line) => line.kind === "instruction");
-    return first === undefined ? undefined : FROM.exec(first.raw.trim())?.[1];
-};
-
-// Whether the overlay's first instruction pins it to the official sandbox image.
-export const hasOfficialBase = (content: string): boolean => {
-    const base = overlayBase(content);
-    return base !== undefined && isOfficialSandboxImage(base);
-};
-
-/* A whole composed overlay, as an executor that did not compose it must read it: one leading FROM on the
- * official image, then RUN and ENV only. Comments pass, the runtime directive included, since a composed
- * overlay is where the daemon's own capability fragments put it and the executor that honours it (ic) reads
- * it from there; an executor that cannot honour it (a VM is already privileged) ignores it. Answers the
- * offending line, or undefined. An overlay with no instruction at all is refused: there is nothing to build. */
-export const lintOverlay = (content: string): string | undefined => {
-    let first = true;
-    for (const { raw, kind } of overlayLines(content)) {
-        if (kind !== "instruction") {
-            continue;
-        }
-        const line = raw.trim();
-        if (first) {
-            first = false;
-            const base = FROM.exec(line)?.[1];
-            if (base === undefined || !isOfficialSandboxImage(base)) {
-                return raw;
-            }
-            continue;
-        }
-        if (!RUN_OR_ENV.test(line)) {
-            return raw;
-        }
-    }
-    return first ? "" : undefined;
-};
-
-/* The same overlay on a different base: the first FROM rewritten, everything else byte-identical. An
- * executor applies an approved recipe on the base IT runs (a newer release than the one the daemon composed
- * against, a rollback pin), and hashes the content the owner approved rather than this rewrite, so the
- * environment hash stays the reviewed one. Content whose first instruction is not a FROM is returned as is. */
-export const rewriteOverlayBase = (content: string, base: string): string => {
-    let done = false;
-    return overlayLines(content)
-        .map(({ raw, kind }) => {
-            if (done || kind !== "instruction") {
-                return raw;
-            }
-            done = true;
-            return FROM.test(raw.trim()) ? raw.replace(FROM, `FROM ${base}`) : raw;
-        })
-        .join("\n");
-};

package/src/path-refs.ts

@@ -1,59 +0,0 @@
-/* Which file a NAMED reference means. A path written in prose is only loosely anchored to the workspace: an
- * agent that has been working in `_editor/web/src` writes `pages/workspace/Foo.vue`, and a turn running in an
- * isolated worktree prints `/history/worktrees/<id>/_editor/web/src/foo.ts`, neither is the workspace-relative
- * path the file routes speak, but both END in it.
- *
- * So a reference is resolved by matching progressively shorter TAILS of it against the real tree. The rules
- * live here, in the contract package, because both sides run them: the browser first against the workspace
- * tree it already has cached, then the daemon (/workspace/resolve) against the iq engine's full sweep, which
- * sees the files the capped tree walk left out. Two matchers that disagreed would make a link's destination
- * depend on which one answered. */
-
-// How many leading segments a reference may carry that the workspace doesn't (the `/history/worktrees/<id>/`
-// lead of a worktree path is 3; a foreign absolute root is rarely deeper).
-const MAX_DROPS = 6;
-// A tail is never cut down to a bare filename: `index.ts` names a hundred files in a monorepo and picking one
-// at random is worse than not linking. The link grammar never emits a slash-less reference either.
-const MIN_SEGMENTS = 2;
-// Enough candidates for a picker; a reference matching more than this is ambiguous by any measure.
-export const MAX_REF_CANDIDATES = 10;
-
-// The tails worth matching, longest (most specific) first. `root` is the container workspace root: a path
-// under it is already the answer minus that lead, and a path under any OTHER absolute root (a worktree) still
-// mirrors the layout below its own lead, which the successive drops strip.
-export const referenceTails = (raw: string, root: string): readonly string[] => {
-    const normalized = raw.replaceAll(`\\`, `/`).replace(/^\.\//, ``);
-    const anchored = normalized.startsWith(`${root}/`) ? normalized.slice(root.length + 1) : normalized.replace(/^\/+/, ``);
-    const segments = anchored.split(`/`).filter((segment) => segment !== `` && segment !== `.`);
-    const tails: string[] = [];
-    for (let drop = 0; drop <= MAX_DROPS && segments.length - drop >= MIN_SEGMENTS; drop++) {
-        tails.push(segments.slice(drop).join(`/`));
-    }
-    return tails;
-};
-
-// The paths that genuinely END in `tail` on a segment boundary, best first, the shared ranking both matchers
-// return their candidates in. Shallowest wins: `pages/Foo.vue` means the app's page, not the copy six
-// directories down in a fixture tree. (The daemon's glob is anchored only at the string level, `**/pages/x.vue`
-// also matches `mypages/x.vue`, so the boundary is enforced here rather than by the pattern.)
-export const rankRefCandidates = (tail: string, paths: readonly string[]): readonly string[] =>
-    paths
-        .filter((path) => path === tail || path.endsWith(`/${tail}`))
-        .toSorted((a, b) => a.split(`/`).length - b.split(`/`).length || a.length - b.length || (a < b ? -1 : 1))
-        .slice(0, MAX_REF_CANDIDATES);
-
-/* IS THIS FILE TEST CODE, the one classification rule for every surface that splits a diff into "the
- * change" and "the proof". The agent review header answers "how much of this is tests?" with it; anything
- * else that wants the split (fleet cards, commit summaries) must use this same predicate, because two
- * classifiers that disagree turn the readout into a lie the user can't detect.
- *
- * Convention-based, matching what this monorepo (and the ecosystems it scaffolds) actually writes: a
- * `.test.` / `.spec.` filename in any extension, a `__tests__` / `__fixtures__` directory anywhere on the
- * path, an `e2e-harness`, or a test-runner config. Deliberately NOT "anything containing 'test'": a
- * `testimonials/` page or a `latest.ts` is product code, and a false "tests" tag is worse than a missed one,
- * it tells a reviewer not to look. */
-const TEST_DIRS = new Set([`__tests__`, `__fixtures__`, `__mocks__`, `__snapshots__`]);
-const TEST_FILE =
-    /(?:^|\/)(?:[^/]+\.(?:test|spec)\.[^/.]+|[^/]*\.e2e\.[^/]+|e2e-harness\.[^/]+|(?:vitest|jest|playwright)(?:\.[\w-]+)*\.config\.[^/]+)$/;
-
-export const isTestPath = (path: string): boolean => TEST_FILE.test(path) || path.split(`/`).some((segment) => TEST_DIRS.has(segment));