@intentic/sandbox-contract 1.239.0 → 1.242.0

package/src/schemas/approvals.ts

@@ -0,0 +1,174 @@
+// approvals: things the agent prepared and may not do until the owner says yes (.intentic/config/approvals/<id>.json)
+import { z } from "zod";
+import { entryId } from "./internal.js";
+
+/* ONE QUEUE FOR EVERYTHING THAT WAITS ON A YES, and the test for what belongs in it: the agent prepared an exact
+ * thing, the owner's click releases it, a machine then carries out precisely that thing, and the outcome is
+ * written back. A post is the first such thing and was the whole of this file (it was `drafts`); a hotel
+ * booking, a payment, a message sent under the owner's name are the same shape with a different payload, and
+ * each of them arriving as its own inbox is how a product grows five tiles that all say "approve".
+ *
+ * So the record is an ENVELOPE plus a KIND. The envelope is what every approval shares and what the queue, the
+ * badge and the daemon act on: who it acts as, when it is due, where it stands, what happened. The kind is what
+ * the row draws and the daemon dispatches on, a discriminated union so a new kind is one variant here, one
+ * body component in the extension and one executor in the daemon, and nothing else moves.
+ *
+ * What does NOT belong here, and why the line is drawn where it is: an inbox of FACTS (the issues queue, where
+ * a crash arrived and the owner's verbs are resolve / ignore / investigate) has no prepared thing to release,
+ * and a hold a RUNNING turn is blocked on (a permission card, a spend offer) lives in the conversation, because
+ * a queue is the wrong latency for a click somebody is spinning on.
+ *
+ * One JSON file per approval. The AGENT creates them with its normal file tools, it can't call daemon routes,
+ * the same split as the environment proposal, while the daemon edits/deletes them on the owner's behalf, so
+ * the two writers never share a file. The id IS the filename (entryId charset ⇒ path-safe); the body never
+ * carries it. */
+
+export const ApprovalKindSchema = z.enum(["post", "action"]);
+export type ApprovalKind = z.infer<typeof ApprovalKindSchema>;
+
+/* proposed (agent) → approved (owner) → running (executor, set BEFORE acting so a dead turn can't do it twice)
+ * → done | failed. Reject = delete the file; retry = re-approve a failed one. The names are deliberately not a
+ * post's ("posting", "posted"): they are read by every kind, and a booking is not "posted". */
+export const ApprovalStatusSchema = z.enum(["proposed", "approved", "running", "done", "failed"]);
+export type ApprovalStatus = z.infer<typeof ApprovalStatusSchema>;
+
+/* THE ENVELOPE, spread into every variant below (zod's discriminated union wants flat objects, not an extended
+ * base), which is also why a variant's own fields sit beside these rather than under a `payload` key: the file
+ * an agent writes stays one level deep, and "which fields are mine" is answered by the variant's schema. */
+const envelope = {
+    /* WHOSE NAME THIS ACTS UNDER, a PersonaSchema id, handed to the executing turn as AgentTurnSchema.actsAs.
+     * Required in practice for every post outside DIRECT_PUBLISH_PLATFORMS, and the reason is the whole shape
+     * of turnPersona: acting through a browser needs a logged-in account, and an UNATTENDED turn that names no
+     * persona is denied every account there is. Without this field the executor could only wake such a turn,
+     * one structurally unable to reach the login the post needs, which read from inside the turn as "this
+     * account is not connected" and cost two approved posts before anyone traced it back here.
+     *
+     * A PERSONA RATHER THAN AN ACCOUNT ID, because that is the vocabulary the rest of the system already speaks:
+     * `actsAs` is the only pin turnPersona honours, and a card carries the workspace scope the turn also needs to
+     * write this file's own status back. Naming the account directly would invent a second way to say the same
+     * thing, and the two would disagree the first time a card's accounts changed.
+     *
+     * The daemon never guesses it. One site can be connected several times over, five Reddit logins here, and
+     * picking for the owner means picking wrong in public, with no undo. A post that needs a turn and names
+     * nobody is failed with that sentence instead of sent. An ACTION that names nobody runs with no accounts,
+     * which is a legitimate choice for work that needs none. */
+    actsAs: entryId
+        .optional()
+        .describe(
+            "Whose name it acts under. Needed for anything that requires being logged in, because an unwatched turn naming nobody is allowed no account at all. Never guessed: one site can be connected five times over, and picking for you means picking wrong in public with no undo.",
+        ),
+    // Suggested time (epoch ms, the at/nextRun convention). Optional, the agent may propose without a date and
+    // the owner sets one at approval; an approved item with no date is dated one hold ahead by the daemon.
+    scheduledAt: z
+        .number()
+        .optional()
+        .describe(
+            "When it should happen, in milliseconds. An agent may propose without one and you set it when approving; an approved item with no time goes after a short countdown you can still stop.",
+        ),
+    // Agent-written files only need the kind's own fields; status defaults, the rest are optional, so a
+    // well-formed proposal never lands in `invalid` just for omitting bookkeeping fields.
+    status: ApprovalStatusSchema.default("proposed").describe(
+        "Where it is: proposed by the agent, approved by you, being carried out, done, or failed. Rejecting is deleting it; retrying is approving a failed one again.",
+    ),
+    createdAt: z.number().optional().describe("When it was written, in milliseconds."),
+    // When execution STARTED, stamped with status "running". The executor needs it to tell a run that is under
+    // way from one whose turn died mid-flight, and those two are indistinguishable from the due time: a post
+    // scheduled for last week is not a post that has been sending since last week.
+    startedAt: z
+        .number()
+        .optional()
+        .describe(
+            "When it started being carried out, in milliseconds. Needed to tell a run that is under way from one whose turn died mid-flight, which the scheduled time cannot.",
+        ),
+    finishedAt: z.number().optional().describe("When it was done, in milliseconds."),
+    // What came back, when something did: a post's own address, a booking's confirmation. The one thing a done
+    // row can offer that reading the proposal cannot: the result itself, to go and look at. A URL is drawn as
+    // a link; anything else as the sentence it is.
+    result: z
+        .string()
+        .optional()
+        .describe(
+            "What came back, when something did: the post's own address, a confirmation number. The one thing a finished item can offer that reading it cannot.",
+        ),
+    // Why it failed; set with status "failed". Written for the owner to read in the queue, so it is a sentence
+    // rather than a code.
+    error: z.string().optional().describe("Why it failed, written as a sentence for a person to read rather than as a code."),
+};
+
+/* A POST, the first kind: words that go out in public under the owner's name and cannot be recalled. */
+export const PostApprovalSchema = z.object({
+    kind: z.literal("post").describe("A post to publish somewhere."),
+    // Which skill posts it: "x" | "reddit" | "youtube" | "discord" | …, a bare string so new platforms need
+    // no contract change; an unknown platform simply fails at posting time.
+    platform: z
+        .string()
+        .min(1)
+        .describe("Where it should go. A plain name, so a new site needs no change here; an unknown one simply fails when it tries to post."),
+    content: z.string().min(1).describe("The post itself."),
+    // Reddit posts / YouTube uploads need one.
+    title: z.string().optional().describe("A title, where the site wants one."),
+    /* Where on the platform: subreddit / Discord channel id / community. OR the URL of the thing this post
+     * replies to. A URL target means the post is a reply, and on reddit the difference between a thread's
+     * address and one comment's permalink is the difference between talking to the room and answering the
+     * person: the publisher opens exactly this and replies where it lands. */
+    target: z
+        .string()
+        .optional()
+        .describe(
+            "Where on the site: a community, a channel. Or the address of the thing this replies to, in which case it is a reply, and on some sites the difference between a thread's address and one comment's is the difference between talking to the room and answering the person.",
+        ),
+    // Workspace-relative attachment paths, e.g. ".intentic/config/approvals/media/chart.png".
+    media: z.array(z.string()).optional().describe("Anything to attach, as workspace paths."),
+    ...envelope,
+});
+export type PostApproval = z.infer<typeof PostApprovalSchema>;
+
+/* AN ACTION, the general kind: anything else the agent is about to do that it should not do unasked. A
+ * booking, a purchase, a message to a person, a deletion that cannot be undone. The agent writes what it will
+ * do in words the owner reads (`summary`, `details`), and what it will tell ITSELF to do once released
+ * (`instructions`), because the turn that carries it out is a fresh one, hours later, with none of the
+ * conversation that led here. Executed by an agent turn, always: there is no typed door for "whatever it is". */
+export const ActionApprovalSchema = z.object({
+    kind: z.literal("action").describe("Something the agent will do once you say so."),
+    summary: z.string().min(1).max(200).describe("What will happen, in one line: the row's headline and the confirm dialog's item."),
+    // Markdown. The specifics a yes is being asked for: the hotel and the dates, the amount and the account,
+    // the exact message and its recipient. Everything the owner has to see to be able to say no.
+    details: z.string().optional().describe("The specifics, as Markdown: everything you would want to see before saying yes."),
+    // What the executing turn is told. Written by the agent for its later self, so it names files, ids and
+    // steps rather than saying "do what we discussed".
+    instructions: z
+        .string()
+        .min(1)
+        .describe(
+            "What to do once approved, written for the fresh turn that will do it: names, ids and steps, since it has none of this conversation.",
+        ),
+    ...envelope,
+});
+export type ActionApproval = z.infer<typeof ActionApprovalSchema>;
+
+// The on-disk file body, whichever kind it is.
+export const ApprovalSchema = z.discriminatedUnion("kind", [PostApprovalSchema, ActionApprovalSchema]);
+export type Approval = z.infer<typeof ApprovalSchema>;
+
+// The list row / upsert input: the file body plus its filename id.
+const withId = { id: entryId.describe("The approval's id.") };
+export const PostApprovalSummarySchema = PostApprovalSchema.extend(withId);
+export type PostApprovalSummary = z.infer<typeof PostApprovalSummarySchema>;
+export const ActionApprovalSummarySchema = ActionApprovalSchema.extend(withId);
+export type ActionApprovalSummary = z.infer<typeof ActionApprovalSummarySchema>;
+export const ApprovalSummarySchema = z.discriminatedUnion("kind", [PostApprovalSummarySchema, ActionApprovalSummarySchema]);
+export type ApprovalSummary = z.infer<typeof ApprovalSummarySchema>;
+
+// `invalid` = filenames that failed to parse. Agent-written files are a trust boundary, without this a typo'd
+// approval (or one of a kind this daemon does not know) would silently never run.
+export const ApprovalsListSchema = z.object({
+    approvals: z.array(ApprovalSummarySchema).describe("The queue."),
+    invalid: z
+        .array(z.string())
+        .describe(
+            "Files that could not be read at all, or name a kind this daemon does not know. Listed rather than skipped, because an agent writes these files directly and a malformed one would otherwise never run and never say why.",
+        ),
+});
+export type ApprovalsList = z.infer<typeof ApprovalsListSchema>;
+// entryId, not a bare string: the id becomes a filename under .intentic/config/approvals/.
+export const ApprovalIdParamSchema = z.object({ id: entryId.describe("Which approval.") });

package/src/schemas/ci.ts

@@ -124,22 +124,8 @@ export const CiRunsResponseSchema = z.object({
     repos: z.array(CiRepoSchema).describe("Which workspace repositories are wired to a forge, and how each one's notifications are set up."),
     // Newest first, across all mapped repos.
     runs: z.array(PipelineRunSchema).describe("Runs across all of them, newest first."),
-    // When the owner last opened the pipelines view. Rides the runs response so the rail can decide what is
-    // NEW without a second call, a breakage older than this has already been seen and must not badge again.
-    // Absent ⇒ never opened, so everything counts as unseen.
-    seenAt: z
-        .number()
-        .optional()
-        .describe(
-            "When this was last looked at, in milliseconds, so a badge can tell new breakages from ones already read without a second call. Absent means never, so everything counts as new.",
-        ),
 });
 export type CiRunsResponse = z.infer<typeof CiRunsResponseSchema>;
-// Stamping the view as read hands back the timestamp it wrote, so the client updates without a refetch.
-export const CiSeenResponseSchema = z.object({
-    seenAt: z.number().describe("The timestamp that was written, handed back so a caller can update without asking again."),
-});
-export type CiSeenResponse = z.infer<typeof CiSeenResponseSchema>;
 // rerun/cancel/fix address a run by repo + vendor id; the daemon re-resolves repo → project + token per call,
 // so a stale card can't act on a project the workspace no longer maps to.
 export const CiRunParamSchema = z.object({
@@ -181,21 +167,28 @@ export type CiFixResponse = z.infer<typeof CiFixResponseSchema>;
  * dialog that started it, and is gone. Nothing survives a daemon restart because nothing needs to: the next
  * push asks again. */
 
-/* Where a run is.
+/* A COMMAND RUN ON A CLICK, in a visible terminal, with a verdict and a quotable tail: the ONE shape for
+ * everything the daemon runs because the owner pressed a button and then has to be told how it went. The
+ * pre-push check is one (above); the push itself is another (PushRunSchema, schemas/git.ts), because a push
+ * runs the repository's own pre-push hook, which is a suite in disguise. One shape rather than one per
+ * moment, so a field the browser learns to read for the check (the terminal to open, the tail to quote, the
+ * kill to distinguish from the timeout) is read for the push by the same code, and cannot drift.
+ *
+ * Where a run is.
  *
  *   idle     , nothing has run in this daemon's life, or the last run was cleared.
- *   running  , the check is live. Its output is the terminal's (`session`), not this object's.
- *   passed   , exited 0. The push goes.
- *   failed   , exited non-zero, or was killed by prepushTimeoutMs (`timedOut`). The state a fix answers.
- *   error    , the check could not run at all: the command was not spawnable. NOT a fix-able failure, because
- *               there is nothing wrong with the code, the command is misconfigured, and saying "tests failed"
- *               would send an agent hunting a bug that isn't there.
+ *   running  , the command is live. Its output is the terminal's (`session`), not this object's.
+ *   passed   , exited 0. The push goes (or went).
+ *   failed   , exited non-zero, or was killed by its ceiling (`timedOut`). The state a fix answers.
+ *   error    , the command could not run at all: it was not spawnable. NOT a fix-able failure, because there
+ *               is nothing wrong with the code, the command is misconfigured, and saying "tests failed" would
+ *               send an agent hunting a bug that isn't there.
  *   cancelled, the user stopped the run.
  */
-export const PrepushStatusSchema = z.enum(["idle", "running", "passed", "failed", "error", "cancelled"]);
-export type PrepushStatus = z.infer<typeof PrepushStatusSchema>;
-export const PrepushRunSchema = z.object({
-    status: PrepushStatusSchema.describe(
+export const CommandRunStatusSchema = z.enum(["idle", "running", "passed", "failed", "error", "cancelled"]);
+export type CommandRunStatus = z.infer<typeof CommandRunStatusSchema>;
+export const CommandRunSchema = z.object({
+    status: CommandRunStatusSchema.describe(
         "Where the run is. Failed and error are deliberately different: failed means the code is wrong, error means the command could not be run at all, and calling the second one a test failure would send an agent hunting a bug that is not there.",
     ),
     // The command this run executed, echoed rather than read back from settings: a result read after the
@@ -232,4 +225,4 @@ export const PrepushRunSchema = z.object({
             "The end of what it printed, as plain text with the colour codes and redrawn progress lines resolved away. The end rather than the beginning, because a suite's verdict is at the end. Empty while it runs, and for one that was killed.",
         ),
 });
-export type PrepushRun = z.infer<typeof PrepushRunSchema>;
+export type CommandRun = z.infer<typeof CommandRunSchema>;

package/src/schemas/computers.ts

@@ -133,7 +133,19 @@ export type MachineFlowLine = z.infer<typeof MachineFlowLineSchema>;
  *
  * The machine still enforces its own switches. "Run commands" being off comes back as its own refusal, in its
  * own words, naming the control to flip — exactly as it does for the sandbox ops. */
-export const MachineCommandSchema = z.enum(["mirror-off", "mirror-on"]);
+/* THE SET, and why the file-sync half of it is here beside the mirroring half.
+ *
+ * Both are the same gesture to the person clicking: something this computer is doing for this sandbox, turned
+ * off or on from the row that describes it. They were split for a while by nothing but which one had been built
+ * — mirroring had a button and pausing a file sync had a paragraph telling you to go and find a terminal — and
+ * that is exactly the gap this door exists to close.
+ *
+ * `sync-unpair` is the one that DESTROYS something, and it is deliberately the machine's `sync uninstall
+ * --sandbox`, not this side's idea of unpairing: the agent terminates both Mutagen sessions, drops the local
+ * pairing and self-revokes its enrollment on the way out, so the machine cleans up after itself rather than
+ * leaving a sandbox to guess what it managed to do. Revoking from the SANDBOX side (an unreachable machine, a
+ * laptop that is never coming back) is a different act and a different route, see the enrollment revoke. */
+export const MachineCommandSchema = z.enum(["mirror-off", "mirror-on", "sync-pause", "sync-resume", "sync-unpair"]);
 export type MachineCommand = z.infer<typeof MachineCommandSchema>;
 /* Which paired sandbox the command acts on: the machine's own id for it, as it appears in that machine's report,
  * so nothing here has to re-derive the sanitizing the agent applied. Absent means every sandbox that machine
@@ -195,7 +207,7 @@ export const MachinePairingSchema = z.object({
     /* The SECOND session's word, the one-way mirror carrying the sandbox's state dir down (sync's backupSpec).
      * Reported separately rather than folded into the status above, because the two fail independently and mean
      * different things: the first going quiet stops the owner's edits moving, the second going quiet stops their
-     * personas, skills, automations, drafts and transcripts from surviving the sandbox. A backup that is not
+     * personas, skills, automations, approvals and transcripts from surviving the sandbox. A backup that is not
      * running is only dangerous while nobody knows, so it gets its own word on the line. */
     backupStatus: z.string().optional(),
 });
@@ -294,13 +306,39 @@ export type ComputerGap = z.infer<typeof ComputerGapSchema>;
  * enrolled ssh key's comment vs. the capability id the user typed, so the two are reconciled on the `hostname`
  * their reports agree on, and left as separate rows when there is nothing to reconcile them by. Guessing that two
  * differently-named machines are the same one would merge two people's laptops on a shared sandbox. */
+/* THE DESKTOP-SYNC ENROLLMENT BEHIND A ROW, which used to be a boolean and could not be.
+ *
+ * `syncEnrolled: true` answered "is this machine paired" and nothing a reader standing in front of the row
+ * actually asks next: WHICH half of desktop sync it holds (files and ports, or ports alone), whether it has
+ * ever used the enrollment, and how to name it when they want it gone. Those three lived on /system/sync
+ * instead, as one machine's worth of `syncingFrom` plus a list of `mirroredBy` names, which is the sandbox-level
+ * shape this view exists to stop being: one card claiming a sandbox has A desktop sync, over a list of the
+ * several computers that actually do.
+ *
+ * `machine` is the enrollment's own name for the box (the ssh key's comment). It is what the reports are filed
+ * under, and it is the id the revoke route takes — the same string, so a row can revoke exactly the enrollment
+ * it is drawn from. Two machines that present the same comment share one enrollment identity throughout the
+ * daemon (reports included); that is a pre-existing property of naming machines by their key comment, and this
+ * field inherits it rather than inventing a second identity that would disagree with the first. */
+export const ComputerSyncSchema = z.object({
+    machine: z.string(),
+    /* Which half. "sync" is files AND ports and is SINGLE-HOLDER for the sandbox; "mirror" is ports only and any
+     * number of machines may hold one. The row says which, because "your laptop is paired" is read as the first
+     * by somebody who has the second, and then their files are not where they expect them. */
+    mode: z.enum(["sync", "mirror"]),
+    // When this machine last USED its enrollment (its watcher's own polls stamp it). Absent on one that never
+    // has, which is exactly what a setup that did not finish leaves behind, and must not read as healthy.
+    seenAt: z.number().optional(),
+});
+export type ComputerSync = z.infer<typeof ComputerSyncSchema>;
 export const ComputerSchema = z.object({
     // Stable row key: the reported hostname when either door produced one, else the name that door knows it by.
     key: z.string(),
     // What to call it on screen, the user's own name for the machine wherever one exists.
     label: z.string(),
-    // Whether a desktop-sync enrollment exists for this machine (it syncs files and/or mirrors ports).
-    syncEnrolled: z.boolean(),
+    // The desktop-sync enrollment this machine holds with this sandbox, absent when it has none (a computer
+    // reached only through its `host` capability).
+    sync: ComputerSyncSchema.optional(),
     // The host capability's id, when this machine is also a connected computer. Absent otherwise.
     hostId: z.string().optional(),
     // Host-capability liveness. Absent when there is no host capability, which is NOT the same as offline.
@@ -327,9 +365,16 @@ export const ComputerSchema = z.object({
 });
 export type Computer = z.infer<typeof ComputerSchema>;
 export const ComputersListSchema = z.object({ computers: z.array(ComputerSchema) });
-// GET /system/sync, the enrollment state the Desktop sync card is built on, plus what each enrolled machine has
-// said about itself. `machines` is optional because a daemon predating machine reports omits it, and an SPA is
-// routinely newer than the daemon it is pointed at during a rolling update.
+/* GET /system/sync: what desktop sync is doing for this sandbox, WITHOUT naming any one machine as the answer.
+ *
+ * It used to carry `syncingFrom` + `syncSeenAt` + `mirroredBy`, which is the enrollment list flattened into one
+ * holder and a list of everybody else — the shape a card that believed a sandbox has A desktop sync needed, and
+ * the reason that card kept restating facts the Computers list beside it already had per machine. Every one of
+ * those now rides on the machine's own row (ComputerSync), where a reader can act on it.
+ *
+ * What is left is what is genuinely about the SANDBOX rather than about any computer: whether sync is possible
+ * here at all, whether anything at all is enrolled, and the raw reports, which is the cheap ambient read the
+ * rail's badge lives on (it must never fan out to somebody's laptop just to decide whether to draw a chip). */
 export const SyncStatusSchema = z.object({
     enrolled: z.boolean(),
     /* Whether this sandbox can do desktop sync at all. It used to be the SSH hostname the laptop would dial, and
@@ -338,10 +383,6 @@ export const SyncStatusSchema = z.object({
      * surface now, so a sandbox that can answer this read can also sync. Kept as a field rather than assumed,
      * because the card branches on it and a daemon too old to say is one that should not be offered sync. */
     available: z.boolean().optional(),
-    // The single machine holding file sync, and when its heartbeat last landed.
-    syncingFrom: z.string().optional(),
-    syncSeenAt: z.number().optional(),
-    mirroredBy: z.array(z.string()).optional(),
     machines: z.array(MachineReportSchema).optional(),
 });
 export type SyncStatus = z.infer<typeof SyncStatusSchema>;

package/src/schemas/environment.ts

@@ -70,8 +70,22 @@ export const EnvironmentRecurringSchema = z.object({
     live: z.boolean(),
     drafted: z.boolean().optional(),
     declined: z.boolean().optional(),
+    /* The Dockerfile step that would bake this tool, when its ecosystem has one that follows from the name
+     * alone (auto-drafts.ts `stepFor`). Sent rather than re-derived in the browser because it is the SAME string
+     * the owner would approve, and because its presence is the honest answer to "can this be fixed by pressing a
+     * button?": absent means the fix is a judgement call (which pip package, replaying which installer) and the
+     * card offers an agent instead. */
+    step: z.string().optional(),
 });
 export type EnvironmentRecurring = z.infer<typeof EnvironmentRecurringSchema>;
+/* The owner's answer to ONE line of that list. `adopt` writes the tool's overlay draft now, without waiting for
+ * the sweep to re-earn it; `dismiss` tombstones it so nothing proposes it again; `restore` undoes a dismissal.
+ * One route rather than three because it is one decision surface about one ledger entry. */
+export const EnvironmentRuntimeDecisionSchema = z.object({
+    tool: z.string().min(1),
+    decision: z.enum(["adopt", "dismiss", "restore"]),
+});
+export type EnvironmentRuntimeDecision = z.infer<typeof EnvironmentRuntimeDecisionSchema>;
 export const EnvironmentSchema = z.object({
     proposal: environmentFileSchema.optional(),
     // The owner-approved agent-written custom section (.intentic/config/environment.custom.Dockerfile).
@@ -142,116 +156,23 @@ export const EnvironmentItemSchema = z.object({
 export type EnvironmentItem = z.infer<typeof EnvironmentItemSchema>;
 export const EnvironmentContentsSchema = z.object({ items: z.array(EnvironmentItemSchema) });
 export type EnvironmentContents = z.infer<typeof EnvironmentContentsSchema>;
-/* ---- portability: exporting a sandbox's environment and restoring it into a fresh one ----
+/* ---- portability: exporting a sandbox's environment ----
  *
  * A sandbox is four stores, not one: `/work` (the workspace and the daemon's manifests), `/history` (every
  * repo's real git dir, the fleet registry, the ledgers), the CONTAINER (the built overlay image plus the env
  * the run contract replays) and the AI-provider credential root. A bundle carries the first two, declared entry
  * by entry in WORKSPACE_STATE_FILES / HISTORY_STATE_FILES. It cannot carry the other two, and the honest
- * consequence is that an import ends in a REPORT rather than a claim of equivalence, the container has no
+ * consequence is that taking one in ends in a REPORT rather than a claim of equivalence, the container has no
  * docker socket, so only the host can rebuild the image the overlay describes.
  *
  * The bundle's manifest (BundleManifestSchema) lives in definition.ts beside the sandbox DEFINITION it embeds:
  * a bundle is definition + state, and keeping the two schemas together is what keeps the two export doors from
- * drifting into different answers about what an environment is. */
-
-// What a restore actually did. `needsAction` is the part that matters: the environment rebuild command, the
-// credentials to re-enter, the logins to redo, each one a thing the target cannot do for itself.
-export const ImportReportSchema = z.object({
-    restored: z.object({ workspaceFiles: z.number(), historyFiles: z.number(), repos: z.array(z.string()), bytes: z.number() }),
-    // Entries the bundle carried that this daemon refused to write (an identity file, an escaping path), empty
-    // for any bundle a matching exporter produced, and a tamper signal when it is not.
-    refused: z.array(z.string()),
-    needsAction: z.array(z.object({ subject: z.string(), detail: z.string() })),
-});
-export type ImportReport = z.infer<typeof ImportReportSchema>;
-/* ---- migrations: importing a FOREIGN assistant's setup (Hermes, OpenClaw) ----
- *
- * A different crossing than a bundle restore, and deliberately a different surface: a bundle is our own format,
- * re-derived entry by entry against the state manifests, while a migration reads a directory some OTHER
- * program laid out (`~/.hermes`) and TRANSLATES it into native things, skills, automations, capabilities,
- * merged memory. Nothing foreign is executed or copied verbatim into daemon state; every item lands through the
- * same write paths the settings/skills/automations/capabilities surfaces use, which is what keeps an imported
- * setup editable and deletable in the ordinary UI the day after (docs/assistant-import-design.md).
+ * drifting into different answers about what an environment is.
  *
- * The flow is PREVIEW-FIRST, mirroring what these tools' own `migrate` commands taught their users to expect:
- * `plan` parses the uploaded archive into an itemized checklist and holds the upload in memory under a token;
- * `apply` names the ticked item ids and the token. The plan is RE-DERIVED from the held archive at apply, the
- * wire plan is a rendering for the owner, never the input the write trusts (restore.ts's rule, kept). */
-export const MigrationSourceSchema = z.enum(["hermes", "openclaw"]);
-export type MigrationSource = z.infer<typeof MigrationSourceSchema>;
-// What an item becomes here, not what it was there, the apply loop dispatches on this, and the checklist
-// groups by it so the owner reads "3 skills, 2 automations" rather than a foreign directory listing.
-export const MigrationTargetSchema = z.enum(["memory", "skill", "automation", "capability", "secret", "file"]);
-export type MigrationTarget = z.infer<typeof MigrationTargetSchema>;
-export const MigrationItemSchema = z.object({
-    // Deterministic (derived from the source artifact, e.g. `skill:weather`), so the ids the owner ticked name
-    // the same items when the plan is re-derived at apply.
-    id: z.string(),
-    target: MigrationTargetSchema,
-    // The checklist line, plain words: "Skill, weather", "Nightly digest (9:00 every day)".
-    label: z.string(),
-    detail: z.string().optional(),
-    /* The default tick. False marks the items the owner should read before taking, a server URL that points at
-     * localhost on the OLD machine, an .env key that looks like tuning rather than a credential. They still
-     * import fine when ticked; the flag is the adapter's judgment, not a gate. */
-    recommended: z.boolean(),
-    // Names of the secrets this item would store (never values, values stay in the held archive until apply,
-    // and only move when the apply says includeSecrets). Empty for items that carry none.
-    secrets: z.array(z.string()),
-});
-export type MigrationItem = z.infer<typeof MigrationItemSchema>;
-export const MigrationNeedsActionSchema = z.object({ subject: z.string(), detail: z.string() });
-export const MigrationPlanSchema = z.object({
-    source: MigrationSourceSchema,
-    // Names the held upload for the apply call. Minted per plan; a new upload replaces the held one.
-    token: z.string(),
-    items: z.array(MigrationItemSchema),
-    // What the adapter saw and will not move, sessions, logs, pairing state, listed rather than silent.
-    refused: z.array(z.string()),
-    // What is already known not to move mechanically (channels to reconnect, a model to pick), the same
-    // honesty ImportReportSchema carries, surfaced at PREVIEW time so the owner ticks with open eyes.
-    needsAction: z.array(MigrationNeedsActionSchema),
-});
-export type MigrationPlan = z.infer<typeof MigrationPlanSchema>;
-/* One of the owner's own computers, as an import SOURCE, the answer to "where is my setup" that needs no
- * packing at all. Read on the card's first render for every enrolled machine, so the offer appears before the
- * owner has read a single instruction.
- *
- * `found` absent means "connected, and nothing to import here", which is a real answer worth rendering
- * quietly, not an error: the machine may simply be a different one from the machine the assistant runs on. */
-export const MigrationHostSchema = z.object({
-    id: z.string(),
-    online: z.boolean(),
-    found: MigrationSourceSchema.optional(),
-    // Why this machine cannot be read right now, when it cannot, offline, or its own refusal, in its words.
-    detail: z.string().optional(),
-});
-export const MigrationHostsSchema = z.object({ hosts: z.array(MigrationHostSchema) });
-export type MigrationHost = z.infer<typeof MigrationHostSchema>;
-// Read the setup off a connected computer instead of an upload. Answers with a plan, exactly as the upload
-// route does, everything after this point is identical whichever door the setup came through.
-export const MigrationScanSchema = z.object({ host: z.string().min(1) });
-export const MigrationApplySchema = z.object({
-    token: z.string(),
-    // The ticked item ids. Ids the re-derived plan does not contain are ignored rather than erroring, the
-    // archive is the truth, and a stale checklist must not block the items that still exist.
-    items: z.array(z.string()),
-    // The owner's explicit consent to move credential VALUES (mirrors the bundle export's `?secrets=`, and the
-    // `--include-secrets` these tools' own migrate commands require). Off: secret items are skipped and
-    // capability configs land without their keys.
-    includeSecrets: z.boolean(),
-});
-export type MigrationApply = z.infer<typeof MigrationApplySchema>;
-export const MigrationReportSchema = z.object({
-    applied: z.array(z.object({ id: z.string(), target: MigrationTargetSchema, label: z.string() })),
-    // Items that were ticked and did not land, each with the reason, a full disk, an env store that needs
-    // DevOps active. Distinct from `refused`, which is the class of things never attempted.
-    failed: z.array(z.object({ id: z.string(), label: z.string(), error: z.string() })),
-    refused: z.array(z.string()),
-    needsAction: z.array(MigrationNeedsActionSchema),
-});
-export type MigrationReport = z.infer<typeof MigrationReportSchema>;
+ * ONLY THE OUTBOUND HALF IS HERE. Taking a bundle IN is not a surface of its own any more: it is one of the
+ * four sources the arrival pipeline reads (arrival.ts), beside a definition and the two foreign assistants,
+ * because all four answer the same question and used to answer it three different ways. */
+
 /* One export sitting in the daemon's export directory, the ARTIFACT a bundle is, rather than the request that
  * produced it. Packing takes minutes over a real workspace, so tying it to a response made it a property of one
  * browser tab: a refresh abandoned the work and left nothing to come back to. It is a file now, and every field