@intentic/sandbox-contract 1.348.0 → 1.350.0

package/src/contracts/agents.contract.ts

@@ -4,7 +4,7 @@ import { AgentToolChildrenSchema, SessionTranscriptSchema } from "../events/tran
 import { AgentTranscriptSchema } from "../events/agent-transcript.js";
 import { AgentAssignSchema, AgentAutoLandSchema, AgentBreakPolicySchema, AgentFileDiffQuerySchema, AgentIdSchema, AgentToolChildrenQuerySchema, AgentTranscriptQuerySchema, AgentIdsSchema, AgentLandSchema, AgentReactSchema, AgentRenameSchema, AgentStopJobSchema, AgentStopWatchingSchema, AgentSubagentQuerySchema, AgentsArchivedSchema, AgentsMovedSchema, AgentsRemovedSchema, AgentSummarySchema, AgentUnsentSchema, LandResultSchema } from "../schemas/agents.js";
 import { AgentSearchQuerySchema, AgentSearchResultSchema } from "../schemas/agent-search.js";
-import { AgentsAttentionSchema, AgentsListSchema } from "../schemas/agents-list.js";
+import { AgentsAttentionSchema, AgentsListSchema, HomeConversationSchema } from "../schemas/agents-list.js";
 import { AgentChangesSchema, AgentConflictsSchema, AgentIgnoredSchema, AgentScratchSchema, AgentHistorySchema } from "../schemas/git/git.js";
 import { FileDiffSchema } from "../schemas/history.js";
 import { OkSchema } from "../schemas/shared.js";
@@ -43,6 +43,29 @@ export const agentsContract = {
         })
         .meta({ floor: "owner", control: "never", panel: false })
         .output(AgentsAttentionSchema),
+    // Every member's own, guests' too: the count a rail chip of the master view wears for this sandbox, over the caller's
+    // own conversations rather than the fleet, so a member's chip never counts somebody else's waiting work.
+    attentionMine: procedure
+        .route({
+            method: "GET",
+            path: "/agents/attention/mine",
+            summary: "What needs you, and what is working, of your own conversations",
+            description:
+                "The same two counts as `attention`, over only the conversations you answer for (and their subagents, through their family's one card). What a sandbox's icon shows in the master view without reading the whole fleet.",
+        })
+        .meta({ guest: true })
+        .output(AgentsAttentionSchema),
+    // The id is minted here, from the verified caller, never from a body: a client deriving it could name somebody else's.
+    home: procedure
+        .route({
+            method: "GET",
+            path: "/agents/home",
+            summary: "Your home conversation in this sandbox",
+            description:
+                "The one long-running conversation the master view opens on this sandbox, yours alone among its members: its id, its card once it has started, and whether the work it accepts lands by itself. It orchestrates subagents, judges their work with review and test sessions, and merges what it accepts.",
+        })
+        .meta({ guest: true })
+        .output(HomeConversationSchema),
     archived: procedure
         .route({
             method: "GET",

package/src/ids/conversation-ids.test.ts

@@ -1,5 +1,8 @@
 import {
     CI_FIX_PREFIX,
+    CONVERSATION_ID,
+    homeConversationId,
+    isHomeConversationId,
     ciFixConversationId,
     fixAttemptId,
     fixAttemptOf,
@@ -136,3 +139,15 @@ test("an attempt id passes the guard and fits, even for the widest run id a forg
         expect(id.length).toBeLessThanOrEqual(64);
     }
 });
+
+// One home conversation per member, derived from who they are: the same in every browser and in the daemon, whatever the
+// email's case, a valid conversation id, and never the email itself.
+test("a home conversation id is its member's alone, stable and folded, and says nothing of the address", () => {
+    const ada = homeConversationId("ada@example.com");
+    expect(homeConversationId(" Ada@Example.COM ")).toBe(ada);
+    expect(homeConversationId("bob@example.com")).not.toBe(ada);
+    expect(CONVERSATION_ID.test(ada)).toBe(true);
+    expect(isHomeConversationId(ada)).toBe(true);
+    expect(isHomeConversationId(newConversationId())).toBe(false);
+    expect(ada).not.toContain("ada");
+});

package/src/ids/conversation-ids.ts

@@ -180,6 +180,17 @@ export const fnvDigest = (text: string): string => {
     return (hash >>> 0).toString(36).padStart(7, "0");
 };
 
+// A PERSON'S HOME CONVERSATION in one sandbox: the one long-running chat the master view opens on it, one per member,
+// so two people with the same sandbox connected never share it. Derived from the email rather than drawn, so every
+// browser and the daemon name the same conversation without asking, and an email never sits in an id other members read
+// on the board. Two independent FNV digests (64 bits between them): a sandbox's members never come near a collision.
+// The daemon is the one that says which id is whose (`GET /agents/home`); a client computing it is only a shortcut.
+export const HOME_PREFIX = "home-";
+const homeKey = (email: string): string => email.trim().toLowerCase();
+export const homeConversationId = (email: string): string => `${HOME_PREFIX}${fnvDigest(homeKey(email))}${fnvDigest(`home:${homeKey(email)}`)}`;
+// Whether an id is shaped like somebody's home conversation; whose it is takes the email (`homeConversationId`).
+export const isHomeConversationId = (id: string): boolean => id.startsWith(HOME_PREFIX);
+
 // A failing main-line check that no conversation still holding the work could take: keyed by the project and the moment
 // it began failing, so every attempt at one streak shares a base and a later streak in the same project starts over.
 // Seconds in base36 keep it short; the workspace root is spelled `workspace`, since its project folder is empty.

package/src/schemas/agent-people.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+
+// THE PEOPLE ON A CONVERSATION'S CARD: who answers for it, and who marked it. Their own module so agents.ts, the fleet's
+// summary, stays within its size; agents.ts re-exports every name, so importers keep reading them from there.
+
+// One person behind one mark. The instant rides along so the group can be ordered by who was first, which is also the
+// order the names read in.
+export const ReactorSchema = z.object({
+    email: z.string().describe("Who it was, as the sandbox verified them."),
+    name: z.string().optional().describe("What to call them, when their sign-in carried a name. Absent leaves the address to stand for them."),
+    at: z.number().describe("When they marked it, in milliseconds."),
+});
+export type Reactor = z.infer<typeof ReactorSchema>;
+// The member answerable for a conversation: whose questions its cards are, who a reviewer asks about its work. Derived
+// once from the starter, moved only by `agents.assign`; never a program, which is what `startedBy` is for.
+export const SessionOwnerSchema = z.object({
+    email: z.string().describe("Who answers for this conversation, as the sandbox verified them."),
+    name: z
+        .string()
+        .optional()
+        .describe("What to call them, when the sign-in that made them its owner carried a name. Absent leaves the address to stand for them."),
+    since: z.number().describe("When they became its owner, in milliseconds."),
+});
+export type SessionOwner = z.infer<typeof SessionOwnerSchema>;
+// Grouped by emoji on the wire, not as a flat list of presses: every surface draws one chip per emoji, and grouping
+// here is what stops three of them each grouping it differently.
+export const AgentReactionSchema = z.object({
+    emoji: z.string().describe("The mark itself, one emoji, carried as the character rather than as a name that would need a table on both sides."),
+    by: z
+        .array(ReactorSchema)
+        .min(1)
+        .describe(
+            "Everyone wearing this mark, oldest first, each by name. Carried whole rather than as a count, because a chip reading 3 that cannot say whose is a number nobody can answer. Never empty: the last person taking theirs back takes the whole chip with it.",
+        ),
+});
+export type AgentReaction = z.infer<typeof AgentReactionSchema>;

package/src/schemas/agents-list.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { AgentSummarySchema } from "./agents.js";
+import { ConversationIdSchema } from "./agent.js";
 import { AutomationApprovalSchema } from "./automations.js";
 
 // The fleet list: its own module, since it joins conversations (agents.ts) with held automation wakes (automations.ts),
@@ -35,3 +36,18 @@ export const AgentsAttentionSchema = z.object({
     working: z.number().int().nonnegative().describe("How many conversations are producing something right now."),
 });
 export type AgentsAttention = z.infer<typeof AgentsAttentionSchema>;
+
+// The caller's home conversation in this sandbox (ids/conversation-ids.ts homeConversationId), as the master view opens it:
+// the id is the daemon's answer to whose it is, so no client has to derive it, and the card once its first turn opened it.
+export const HomeConversationSchema = z.object({
+    conversationId: ConversationIdSchema.describe(
+        "Your home conversation's id here. Send to it as to any conversation (`POST /agent`, isolated): its first turn opens it as your home.",
+    ),
+    agent: AgentSummarySchema.optional().describe("Its card, once a first turn has opened it. Absent until then."),
+    lands: z
+        .enum(["itself", "asks"])
+        .describe(
+            "What becomes of the work it accepts: `itself`, it lands and commits when its turn ends, because you may merge here; `asks`, it waits for a maintainer, because you may not.",
+        ),
+});
+export type HomeConversation = z.infer<typeof HomeConversationSchema>;

package/src/schemas/agents.ts

@@ -10,6 +10,8 @@ import { AgentNeedSchema } from "./needs.js";
 import { EMOJI_MAX_LENGTH, isSingleEmoji } from "../text/emoji.js";
 import { ProgramAskSchema } from "../events/requests.js";
 import { ReviewTallySchema, TurnProofSchema } from "./work-assurance.js";
+import { AgentReactionSchema, SessionOwnerSchema } from "./agent-people.js";
+export { AgentReactionSchema, ReactorSchema, SessionOwnerSchema, type AgentReaction, type Reactor, type SessionOwner } from "./agent-people.js";
 // A fleet agent is any conversation with a registry entry, keyed by conversationId. Isolated ones own a git worktree
 // (branch agent/<id>); workspace conversations have none, but both share one status/activity/cost lifecycle.
 
@@ -237,37 +239,6 @@ export type LandedMessageDraft = z.infer<typeof LandedMessageDraftSchema>;
 // offer the press that clears a refusal without knowing whose refusal it is.
 export const LandConflictReasonSchema = z.enum(["workspace", "diverged", "binary"]);
 export type LandConflictReason = z.infer<typeof LandConflictReasonSchema>;
-// One person behind one mark. The instant rides along so the group can be ordered by who was first, which is also the
-// order the names read in.
-export const ReactorSchema = z.object({
-    email: z.string().describe("Who it was, as the sandbox verified them."),
-    name: z.string().optional().describe("What to call them, when their sign-in carried a name. Absent leaves the address to stand for them."),
-    at: z.number().describe("When they marked it, in milliseconds."),
-});
-export type Reactor = z.infer<typeof ReactorSchema>;
-// The member answerable for a conversation: whose questions its cards are, who a reviewer asks about its work. Derived
-// once from the starter, moved only by `agents.assign`; never a program, which is what `startedBy` is for.
-export const SessionOwnerSchema = z.object({
-    email: z.string().describe("Who answers for this conversation, as the sandbox verified them."),
-    name: z
-        .string()
-        .optional()
-        .describe("What to call them, when the sign-in that made them its owner carried a name. Absent leaves the address to stand for them."),
-    since: z.number().describe("When they became its owner, in milliseconds."),
-});
-export type SessionOwner = z.infer<typeof SessionOwnerSchema>;
-// Grouped by emoji on the wire, not as a flat list of presses: every surface draws one chip per emoji, and grouping
-// here is what stops three of them each grouping it differently.
-export const AgentReactionSchema = z.object({
-    emoji: z.string().describe("The mark itself, one emoji, carried as the character rather than as a name that would need a table on both sides."),
-    by: z
-        .array(ReactorSchema)
-        .min(1)
-        .describe(
-            "Everyone wearing this mark, oldest first, each by name. Carried whole rather than as a count, because a chip reading 3 that cannot say whose is a number nobody can answer. Never empty: the last person taking theirs back takes the whole chip with it.",
-        ),
-});
-export type AgentReaction = z.infer<typeof AgentReactionSchema>;
 export const AgentSummarySchema = z.object({
     id: z.string().describe("The conversation id, which is how every other call addresses it."),
     sessionId: z.string().optional().describe("The provider session behind the last turn. It is retired whenever the model or account changes."),
@@ -412,6 +383,14 @@ export const AgentSummarySchema = z.object({
     fresh: FreshSessionSchema.optional().describe(
         "Set on a conversation started on another conversation's work without its messages (a code review, a test pass, a person's own ask): which one, for what, and when. Absent for every other conversation.",
     ),
+    // Latched on the opening turn (ids/conversation-ids.ts homeConversationId). Rides the summary because it decides who
+    // may see the row at all (auth/fleet-scope.ts visibleTo): its owner, and the sandbox's owner.
+    home: z
+        .literal(true)
+        .optional()
+        .describe(
+            "This is its owner's home conversation in this sandbox: the one long-running chat the master view opens, which orchestrates its own subagents, holds their work until it accepts it, and lands and commits by itself. Only its owner and the sandbox's owner see it. Absent for every other conversation.",
+        ),
     // Root repo's short base sha; per-repo bases stay daemon-internal.
     base: z.string().optional().describe("The commit its private copy started from, shortened."),
     costUsd: z.number().optional().describe("What it has cost so far, in dollars. A subagent's spend is its own and is not folded in here."),

package/src/schemas/conversation-links.ts

@@ -36,6 +36,11 @@ export const FreshSessionSchema = z.object({
     of: ConversationIdSchema.describe("The conversation whose work it started from."),
     kind: FreshKindSchema.describe("What it was opened for: a code review, a test pass, or the person's own ask."),
     at: z.number().describe("When it started, in milliseconds. Work its origin changed after this is work it has not seen."),
+    // An orchestrator judging its own subagent's work (spawn with `freshOf`): the session is still the origin's child, cut
+    // from its work and landing back into it, but it reports to the agent that opened it, which supervises it.
+    by: ConversationIdSchema.optional().describe(
+        "The agent that opened it, when an agent did rather than a person: an orchestrator judging the work of a subagent it spawned. Its report goes to that agent. Absent for a person's session.",
+    ),
 });
 export type FreshSession = z.infer<typeof FreshSessionSchema>;
 

package/src/schemas/device-folder.ts

@@ -42,6 +42,20 @@ export const clearableOnDevice = (conflict: DeviceConflict): boolean =>
 export const DeviceSyncHoldSchema = z.enum(["owner", "gone", "container-missing", "container-trashed", "swap", "unreachable", "low-disk", "transfer"]);
 export type DeviceSyncHold = z.infer<typeof DeviceSyncHoldSchema>;
 
+// HOW FAR A FOLDER'S COPY IS (2026-10-21), in Mutagen's own counts, so nothing walks the folder a second time to say
+// it: what the sending side's last scan holds (`files`, `bytes`, ignored paths left out as the sync leaves them), and
+// while the receiving side stages a pass, how many of that pass's files it has (`stagedFiles` of `stagingFiles`) and
+// how many bytes have crossed (`stagedBytes`). A folder's first copy is one such pass over everything. Each is absent
+// until Mutagen has said it; the whole is absent from an agent older than it, and from a pairing with no session.
+export const DeviceCopySchema = z.object({
+    files: z.number().int().nonnegative().optional(),
+    bytes: z.number().nonnegative().optional(),
+    stagedFiles: z.number().int().nonnegative().optional(),
+    stagingFiles: z.number().int().nonnegative().optional(),
+    stagedBytes: z.number().nonnegative().optional(),
+});
+export type DeviceCopy = z.infer<typeof DeviceCopySchema>;
+
 // The drive reading that paused a pairing for want of room: when (epoch ms), and how much was free of how much.
 export const DeviceLowDiskSchema = z.object({
     since: z.number(),

package/src/schemas/devices.ts

@@ -1,7 +1,7 @@
 // What one of the user's own machines is running.
 import { z } from "zod";
 import { PortNumberSchema } from "./device-commands.js";
-import { DeviceBridgeHoldSchema, DeviceConflictSchema, DeviceLowDiskSchema } from "./device-folder.js";
+import { DeviceBridgeHoldSchema, DeviceConflictSchema, DeviceCopySchema, DeviceLowDiskSchema } from "./device-folder.js";
 import { parseHostConnection, type DeviceFacts, DeviceFactsSchema, MachineIdentitySchema, MachineIdSchema, userDistrosOf, WslEnvironmentSchema } from "./hosts.js";
 import { RollbackTargetSchema, UpdateOutcomeSchema } from "./updates.js";
 import { DEV_VERSION } from "../state/versions.js";
@@ -249,15 +249,15 @@ export const DevicePairingSchema = z.object({
     remoteDir: z.string().optional(),
     // Whether landed work in this project folder is delivered to `localDir` by itself (`deliverProject`). A project
     // sandbox's folder says "auto"; absent means Bring back by hand, as before. (2026-10-21) The folderless
-    // `projectsHost` pairing of the desktop app's one sandbox per computer went with that sandbox; an older agent's report
-    // that still carries it parses, the key dropped.
+    // `projectsHost` pairing of the one sandbox per computer went with it; an older report carrying it parses, key dropped.
     deliver: z.enum(["auto", "off"]).optional(),
     // (2026-10-20) The slug this machine's ic knows the sandbox by: how the desktop app starts or forgets a folder's sandbox.
     slug: z.string().optional(),
     // Machine-owned switch (agent's own `sync mirror off`); absent reads as "on", not merely unknown.
     mirroring: z.enum(["on", "off"]).optional(),
-    // Mutagen's own status word, kept verbatim rather than reduced to a traffic light.
+    // Mutagen's own status word, kept verbatim rather than reduced to a traffic light, and how far its copy is.
     mutagenStatus: z.string().optional(),
+    copy: DeviceCopySchema.optional(),
     // Whole conflict count, including any Mutagen's own state truncates (`excludedConflicts`).
     conflicts: z.number().int().nonnegative().optional(),
     // Conflicted paths, capped at `CONFLICT_PATHS_MAX`; `conflicts` above is the true, uncapped count.
@@ -304,8 +304,7 @@ export const DevicePortSchema = z.object({
     command: z.string().optional(),
 });
 export type DevicePort = z.infer<typeof DevicePortSchema>;
-// The device's one agent process as a single block; `running` also gates whether the rest of the report is still
-// current, a dead loop leaves every other row reading as it did before it died.
+// The device's one agent process; `running` gates whether the rest of a report is current (a dead loop freezes it).
 export const DeviceAgentSchema = z.object({
     running: z.boolean(),
     pid: z.number().int().optional(),
@@ -313,12 +312,13 @@ export const DeviceAgentSchema = z.object({
     installed: z.string().optional(),
     // Build actually serving, stamped in the pidfile; can lag `installed` indefinitely (see `agentBuildSkew`).
     build: z.string().optional(),
-    // When the loop last finished a pass; a live process can have a dead loop (see `agentStalled`).
+    // When the sync loop last moved; absent while nothing is paired (no loop runs). A live process can have a dead loop.
     lastTickAt: z.number().optional(),
 });
 export type DeviceAgent = z.infer<typeof DeviceAgentSchema>;
-// Loop polls every 5s with two 10s network timeouts per pairing; a minute is several passes of slack.
-export const AGENT_STALL_AFTER_MS = 60_000;
+// Stalled only once the agent's own restart of a loop that stopped moving (machine sync/mirror.ts) is overdue.
+export const WATCHER_STALL_MS = 20 * 60_000;
+export const AGENT_STALL_AFTER_MS = WATCHER_STALL_MS + 2 * 60_000;
 export const agentStalled = (agent: DeviceAgent, now: number): boolean =>
     agent.running && agent.lastTickAt !== undefined && now - agent.lastTickAt > AGENT_STALL_AFTER_MS;
 export const DeviceReportSchema = z.object({

package/src/state/workspace-state.test.ts

@@ -398,6 +398,8 @@ describe(`VERSIONED_STATE_PATHS`, () => {
             // Which commands count as heavy, and how many may run at once; a shared-box decision worth a `git log`
             // line.
             `${STATE_DIR}/config/heavy-commands.json`,
+            // What a home conversation reviews, merges and asks a person about; same reason as the safety policy.
+            `${STATE_DIR}/config/home.md`,
             `${STATE_DIR}/config/loop-designs.json`,
             `${STATE_DIR}/config/personas.json`,
             // A persona's prompt and reachable skills: the text that decides how it behaves, same reason as its card.

package/src/state/workspace-state.ts

@@ -100,6 +100,10 @@ const STATE_FILES = [
     // may do unasked, so a fresh sandbox should start already governed and changes should show in review. Absent falls
     // back to `DEFAULT_SAFETY_POLICY`, not unconfigured.
     { path: ".intentic/config/safety.md", invalidates: ["safety-policy"], portability: "carry", versioned: true },
+    // What every home conversation works by (conversations/home/home-policy.ts): when it reviews, tests, merges and asks a
+    // person. `carry`+`versioned` like the safety policy, since it governs what an orchestrator lands unasked. Absent falls
+    // back to `DEFAULT_HOME_POLICY`.
+    { path: ".intentic/config/home.md", invalidates: [], portability: "carry", versioned: true, why: "Read per home turn; no view shows it." },
     // Verdicts the policy above produced, newest first. `derived`/`local`: evidence about this machine, self-trimming,
     // not carried. Own query key, separate from the policy's, since a verdict must not invalidate the document someone
     // is editing.
@@ -305,12 +309,7 @@ const STATE_FILES = [
     // Unlike the settings file, this switch is observed by the Extensions tab's query, so a flip elsewhere shows up
     // live. Toggling doesn't itself rerun the host, that happens via the loader's reconcile, triggered by the tab's own
     // toggle.
-    {
-        path: ".intentic/config/extension-enablement.json",
-        invalidates: ["extensions"],
-        portability: "carry",
-        versioned: true,
-    },
+    { path: ".intentic/config/extension-enablement.json", invalidates: ["extensions"], portability: "carry", versioned: true },
     // Workspace extensions: one directory per extension, written directly by the agent's file tools and live
     // immediately (no clone, no install step). `authored`, unlike `.intentic/extensions/` below which holds clones.
     // `versioned`: every other load path is already reviewable (a git-installed extension's sha, a baked one's image);