@paigy/harness 0.3.0 → 0.3.2

package/dist/cli.js

@@ -23175,6 +23175,79 @@ function detectAll(deps = {}) {
   return CATALOG.map((entry) => detect(entry, deps));
 }
 
+// src/cli-args.ts
+var USAGE = "usage: paigy-harness setup | pair | host [--grant DIR]\u2026 | service | enable-tools [--scope user|project] | hatch NAME [--voice KEY] [--slot SLOT] | handoff | [--harness claude|codex|agy] [--mode bypass|ask] [--cwd DIR] [--identity NAME] [--grace SECONDS] [--doctor] PROMPT\u2026";
+function parseArgs(argv) {
+  const args = { harness: "claude", mode: "bypass", cwd: process.cwd(), doctor: false, help: false, host: false, pair: false, service: false, setup: false, enableTools: false, scope: "user", grant: [], hatch: null, voice: null, slot: null, identity: null, graceSeconds: 90, prompt: "", handoff: false };
+  const words = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const next = () => argv[++i];
+    if (arg === "--harness") {
+      const v = next();
+      if (v !== "claude" && v !== "codex" && v !== "agy") return { error: `--harness must be claude, codex, or agy, got ${v ?? "nothing"}` };
+      args.harness = v;
+    } else if (arg === "--mode") {
+      const v = next();
+      if (v !== "bypass" && v !== "ask") return { error: `--mode must be bypass or ask, got ${v ?? "nothing"}` };
+      args.mode = v;
+    } else if (arg === "--cwd") {
+      const v = next();
+      if (!v) return { error: "--cwd needs a directory" };
+      args.cwd = v;
+    } else if (arg === "--doctor") {
+      args.doctor = true;
+    } else if (arg === "-h" || arg === "--help" || arg === "help") {
+      args.help = true;
+    } else if (arg === "--scope") {
+      const v = next();
+      if (v !== "user" && v !== "project") return { error: `--scope must be user or project, got ${v ?? "nothing"}` };
+      args.scope = v;
+    } else if (arg === "--grace") {
+      const v = Number(next());
+      if (!Number.isFinite(v) || v < 0) return { error: "--grace needs seconds (0 = straight to phone)" };
+      args.graceSeconds = v;
+    } else if (arg === "host") {
+      args.host = true;
+    } else if (arg === "pair") {
+      args.pair = true;
+    } else if (arg === "setup") {
+      args.setup = true;
+    } else if (arg === "service") {
+      args.service = true;
+    } else if (arg === "--grant") {
+      const v = next();
+      if (!v) return { error: "--grant needs a folder to allow" };
+      args.grant.push(v);
+    } else if (arg === "handoff") {
+      args.handoff = true;
+    } else if (arg === "enable-tools") {
+      args.enableTools = true;
+    } else if (arg === "hatch") {
+      const v = next();
+      if (!v) return { error: 'hatch needs a name: paigy-harness hatch "Voice bug hunter"' };
+      args.hatch = v;
+    } else if (arg === "--voice") {
+      args.voice = next() ?? null;
+    } else if (arg === "--slot") {
+      args.slot = next() ?? null;
+    } else if (arg === "--identity") {
+      const v = next();
+      if (!v) return { error: "--identity needs a hatched agent's name" };
+      args.identity = v;
+    } else if (arg?.startsWith("--")) {
+      return { error: `unknown flag ${arg}` };
+    } else if (arg) {
+      words.push(arg);
+    }
+  }
+  args.prompt = words.join(" ");
+  if (args.help) return args;
+  if (!args.doctor && !args.handoff && !args.hatch && !args.host && !args.pair && !args.service && !args.setup && !args.enableTools && !args.prompt) return { error: "a prompt is required (or setup / --doctor / pair / host / service / enable-tools / hatch NAME / handoff)" };
+  return args;
+}
+var ENABLE_TOOLS_COMMAND = "npx -y -p @paigy/mcp@latest paigy-enable-tools";
+
 // ../../packages/sdk/dist/index.js
 import { createRequire as __sdkCreateRequire } from "module";
 import { randomUUID } from "crypto";
@@ -29553,6 +29626,12 @@ var ReceiptEventSchema = external_exports.enum([
   // the recipient opened it
   "answered",
   // the recipient replied
+  // The recipient TURNED THE RING DOWN — CallKit ended it and no answer was ever tapped.
+  // Written by the phone, on the same door that reports the ring itself, so it exists only
+  // when a ring reached a running app and a person did not take it. That is what separates
+  // it from "a ring with no answer", which our own crashes wrote just as readily and which
+  // is why the responsiveness back-off had to be removed (#1144).
+  "declined",
   "escalated",
   // re-reached at a higher level (re-ring / promote)
   "coalesced",
@@ -29561,8 +29640,14 @@ var ReceiptEventSchema = external_exports.enum([
   // deadline passed unanswered
   "woke",
   // the agent was woken for an owed obligation (callback)
-  "gave_up"
+  "gave_up",
   // the budget was spent — stopped re-engaging
+  // The ladder starts over — a silent pickup (the owner's fresh-miss rule, 2026-07-28), a
+  // promote to call, a re-delivery. APPENDED, never a rewind: `ring_step` was a cache of
+  // the escalated-count and a writer rewound it to 0 on every unanswered call (2026-08-24,
+  // nine rings in an hour, `gaveUp` unreachable). A count since the last `restarted` cannot
+  // be rewound by a writer that forgot to advance it.
+  "restarted"
 ]);
 var AttentionSchema = external_exports.object({
   urgency: NotifyLevelSchema,
@@ -29694,7 +29779,7 @@ var NotifyRequestSchema = external_exports.object({
   if (r.ask !== void 0) {
     for (const f of ["context", "select", "points"]) {
       if (r[f] !== void 0)
-        ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: [f], message: `the simplified \`ask\` form takes no ${f} \u2014 the broker derives it (use \`needs\` for multi-part asks)` });
+        ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: [f], message: `the simplified \`ask\` form takes no ${f} \u2014 the broker derives the answer shape from your prose. Drop ${f} and say it in \`ask\` instead ("should I\u2026" for approve/deny, "which of these\u2026" for a pick), passing \`options\` when you're offering concrete alternatives.` });
     }
     return;
   }
@@ -29807,6 +29892,14 @@ var IntentSchema = external_exports.object({
    *  about what cannot answer "is the bot looping less this week?". */
   fault: external_exports.enum(["loop", "unanswered", "overridden", "misheard", "slow", "other"]).optional()
 });
+var RideAlongSchema = external_exports.object({
+  /** The note this came from — assign/clarify/close it through /api/notes/:id. */
+  noteId: external_exports.string(),
+  /** What to do, in the owner's own words (the note's headline). Never model-rewritten. */
+  text: external_exports.string(),
+  /** The thread to report back on, when the note was dispatched over the request rail. */
+  parentId: external_exports.string().nullable()
+});
 var AwaitItemSchema = external_exports.discriminatedUnion("type", [
   external_exports.object({
     type: external_exports.literal("reply"),
@@ -29827,7 +29920,13 @@ var AwaitItemSchema = external_exports.discriminatedUnion("type", [
     transcript: external_exports.string().optional(),
     /** Coverage report (#396), when the ask declared `points`: which of them this
      *  answer addressed. Missing points = re-ask or proceed knowingly partial. */
-    covered: external_exports.array(external_exports.string()).optional()
+    covered: external_exports.array(external_exports.string()).optional(),
+    /** Ride-alongs (RideAlongSchema) — pending work for you, attached to the moment you
+     *  became free. Only `reply` and `idle` carry it: those are the two outcomes that
+     *  END a wait. `remind`, `superseded` and `turn` are mid-flight, and handing an
+     *  agent a side-quest while it is still holding the line is how the main thing gets
+     *  dropped. Absent/empty = nothing owed. */
+    also: external_exports.array(RideAlongSchema).optional()
   }),
   external_exports.object({
     type: external_exports.literal("remind"),
@@ -29862,7 +29961,7 @@ var AwaitItemSchema = external_exports.discriminatedUnion("type", [
       acts: external_exports.array(IntentSchema).nullable().optional()
     })
   }),
-  external_exports.object({ type: external_exports.literal("idle") })
+  external_exports.object({ type: external_exports.literal("idle"), also: external_exports.array(RideAlongSchema).optional() })
 ]);
 var CallbackTriggerSchema = external_exports.enum(["on_done", "on_blocked", "scheduled"]);
 var ScheduleCallbackSchema = external_exports.object({
@@ -29893,6 +29992,12 @@ var PendingRepliesSchema = external_exports.object({
   pending: external_exports.array(
     external_exports.object({ parentId: external_exports.string(), notificationId: external_exports.string(), createdAt: external_exports.string() })
   ),
+  /** WHO YOU ARE on this account (field report 2026-08-28): the name and device the user
+   *  sees for this session's identity. From inside a session there was no way to find out —
+   *  `pair` with no arguments can HATCH a fresh identity, so it is not a safe probe — and an
+   *  agent that cannot tell which agent it is cannot tell whether work addressed to
+   *  "Reta" was addressed to it. Absent only for a token with no pairing behind it. */
+  you: external_exports.object({ name: external_exports.string(), device: external_exports.string().nullable(), tokenId: external_exports.string() }).optional(),
   /** User-initiated requests addressed to this agent; act on them and reply via
    *  contact on the same parentId. Keeps reappearing until you call
    *  set_task_state on its notificationId. */
@@ -29904,12 +30009,21 @@ var PendingRepliesSchema = external_exports.object({
       createdAt: external_exports.string(),
       /** The user seeded this request with a past conversation — call get_thread on it
        *  FIRST and treat the transcript as prior context (#57/#251). */
-      contextParentId: external_exports.string().optional()
+      contextParentId: external_exports.string().optional(),
+      /** STRANDED (field report 2026-08-28): this request was addressed to ANOTHER agent on
+       *  the account — the name here — which has not been seen since it landed, so nobody
+       *  came for it. Handed to you because you are the session that is here. Take it like
+       *  any request (set_task_state claims it, reply with contact on its parentId), and say
+       *  whose it was, because the user chose that agent on purpose. */
+      stranded: external_exports.string().optional()
     })
   ),
   /** Callbacks you owe the user that are now DUE (you said you'd follow up when done,
    *  if blocked, or at a time that has passed). Re-surfaced every sweep until you
    *  fulfill one by calling contact on its parentId. */
+  /** Ride-alongs (RideAlongSchema): notes assigned to this agent that no wake could
+   *  reach. Same array the contact/await replies carry — one queue, every carrier. */
+  also: external_exports.array(RideAlongSchema).optional(),
   owedCallbacks: external_exports.array(
     external_exports.object({ parentId: external_exports.string(), trigger: CallbackTriggerSchema, note: external_exports.string() })
   ),
@@ -29945,7 +30059,11 @@ var NotifyResponseSchema = external_exports.object({
   status: NotifyStatusSchema,
   createdAt: external_exports.string().datetime(),
   answer: UserAnswerSchema.optional(),
-  answeredAt: external_exports.string().datetime().optional()
+  answeredAt: external_exports.string().datetime().optional(),
+  /** Ride-alongs for THIS agent — pending work it should pick up when it's done with
+   *  what it came for. Present on any reply, because an unwakeable agent's only
+   *  reliable moment is one it initiated. Absent/empty = nothing owed. */
+  also: external_exports.array(RideAlongSchema).optional()
 });
 var NotifyPlanUnitSchema = external_exports.object({
   notificationId: external_exports.string(),
@@ -29967,7 +30085,13 @@ var NotifyPlanUnitSchema = external_exports.object({
   proposal: external_exports.object({
     select: SelectShapeSchema,
     options: external_exports.array(external_exports.object({ label: external_exports.string().min(1) })).optional()
-  }).optional()
+  }).optional(),
+  /** What the broker READ this unit as wanting from the human (#952 layer 2): a `decision`
+   *  between alternatives, an `approval` the agent is blocked on, or `knowledge` it just
+   *  needs to know. Reported so the agent can correct a misread the same way it ratifies a
+   *  shape — the read RAISES (a decision always asks) and never silences a question the
+   *  agent declared (#731, #923). */
+  wants: external_exports.enum(["decision", "approval", "knowledge"]).optional()
 });
 var NotifyPlanSchema = external_exports.object({
   units: external_exports.array(NotifyPlanUnitSchema),
@@ -29991,6 +30115,9 @@ var UserResponseSchema = external_exports.object({
 });
 var VoiceKeySchema = external_exports.enum(["rachel", "george", "jessica", "brian", "lily"]);
 var AgendaTurnSchema = external_exports.object({
+  /** Twin coverage (#1089): sibling claim ids this asking turn's answer ALSO settles —
+   *  the planner declares duplicates instead of asking them twice. */
+  coveredIds: external_exports.array(external_exports.string()).optional(),
   /** At most three short spoken sentences. Capped because a turn is a breath: a 1031-char
    *  line went out on 2026-07-28 and the caller could not answer it at all. */
   info: external_exports.array(external_exports.string().min(1)).max(3).default([]),
@@ -30024,6 +30151,7 @@ var AgendaTurnSchema = external_exports.object({
    *  on, the claim stays pending; blocking:true on context = hold for a reply. */
   blocking: external_exports.boolean().optional()
 });
+var CLAIM_STALE_MS = 30 * 6e4;
 var InboxItemSchema = external_exports.object({
   id: external_exports.string(),
   /** The conversation thread + connection this item lives on. Present on the replied
@@ -30043,6 +30171,15 @@ var InboxItemSchema = external_exports.object({
    *  (live 2026-08-10, D35). The API already orders by it; this lets a reader that
    *  re-sorts (grouping, filtering) put an arrival back in the order it was written. */
   seq: external_exports.number().int().optional(),
+  /** HOW MANY units the arrival was cut into. A device reads a LENS, never the arrival —
+   *  `/api/inbox` serves `open`, so the units already settled are gone from it — and a client
+   *  counting what it can see is counting what is LEFT. Walking a three-unit ask on the answer
+   *  screen read "1 of 3", then "1 of 2", then no chip at all, each answer having removed the
+   *  only evidence of itself. How big an arrival is, is a fact about the arrival, so the
+   *  server that can still see every row states it. Absent on any row with no `askId`: a
+   *  unit knows WHICH ask it came from and WHERE it sat in it, and how many there were is
+   *  the one part of its own arrival a single row cannot answer. */
+  units: external_exports.number().int().positive().optional(),
   tokenId: external_exports.string().optional(),
   status: NotifyStatusSchema,
   context: ContextSchema,
@@ -30063,6 +30200,16 @@ var InboxItemSchema = external_exports.object({
    *  while the party called the same dead claim stalled. Absent = no token/no data,
    *  which must never CLAIM stalled. */
   lastSeenAt: external_exports.string().optional(),
+  /** WHEN THE AGENT LAST SAID ANYTHING ABOUT THIS CLAIM — the newest `agent_state` row in
+   *  the `notification_events` ledger (trigger-written since 20260621010000, so every row a
+   *  user can see has one). The age input for `CLAIM_STALE_MS`, and it has to be this rather
+   *  than `createdAt`: a claim is very often picked up long after the row was born — the
+   *  inbox keeps an ANSWERED row visible while the agent works the follow-up, so a question
+   *  asked this morning and claimed a minute ago is eight hours old and one minute into its
+   *  work. Reading the row's birth as the claim's age brands that "No update in 8h" the
+   *  instant the agent picks it up (#997). Absent = pre-trigger row; fall back to
+   *  `createdAt`. */
+  agentStateAt: external_exports.string().datetime().optional(),
   agenda: external_exports.array(AgendaTurnSchema).optional(),
   /** On a replied detail (#397): the next steps the user attached to the answer
    *  ("call back after lunch") — shown so they can see the commitment was captured. */
@@ -30134,11 +30281,23 @@ var SnoozeRequestSchema = external_exports.object({
   requestId: external_exports.string(),
   until: external_exports.string().datetime()
 });
+var APNS_TOKEN_RE = /^[0-9a-fA-F]{64}$/;
 var PushTokenSchema = external_exports.object({
   voipToken: external_exports.string().min(1).optional(),
   alertToken: external_exports.string().min(1).optional(),
   fcmToken: external_exports.string().min(1).optional(),
   platform: external_exports.enum(["ios", "android"])
+}).superRefine((v, ctx) => {
+  if (v.platform !== "ios") return;
+  for (const field of ["voipToken", "alertToken"]) {
+    const token = v[field];
+    if (token === void 0 || APNS_TOKEN_RE.test(token)) continue;
+    ctx.addIssue({
+      code: external_exports.ZodIssueCode.custom,
+      path: [field],
+      message: `not an APNs device token (want 64 hex chars, got ${token.length})`
+    });
+  }
 });
 var MissedCallSchema = external_exports.enum([
   "retry_10m",
@@ -30189,6 +30348,15 @@ var UserSettingsSchema = external_exports.object({
   /** Opt-in to real-phone (PSTN) calls when the app can't ring. Optional, not
    *  defaulted — an older client PATCHing the full object must not clobber it. */
   pstnCalls: external_exports.boolean().optional(),
+  /** The user's IANA timezone (e.g. "America/Bogota"), recorded by the app — it is the
+   *  only party that knows it. REMINDERS are why it exists: "remind me at ten" becomes
+   *  an absolute `due_at` only if we know whose ten. Optional and never defaulted, for
+   *  the same reason `voiceMode` is (a stale client PATCHing the whole object must not
+   *  clobber it) and one more: a GUESSED timezone schedules reminders hours off, and
+   *  that failure reads as the reminder rail being unreliable rather than as a missing
+   *  setting. Absent = a spoken time can't be landed, so the reminder rides the next
+   *  call — honest about what we know. */
+  timezone: external_exports.string().min(1).max(64).optional(),
   /** Account E2EE state (text lane): 'off' (default) = today's plaintext; 'on' =
    *  content is sealed end-to-end between the local agent and the phone. Like
    *  voiceMode, OPTIONAL and NOT defaulted so a stale client PATCHing the full
@@ -30214,6 +30382,15 @@ var HistoryItemSchema = external_exports.object({
   /** When you answered the agent's notification (agent→user only). */
   humanAckedAt: external_exports.string().nullable()
 });
+var ACTIVITY_LINES = 2;
+var ACTIVITY_LINE_MAX = 80;
+var AgentActivitySchema = external_exports.object({
+  /** Oldest first, so the newest line is last — the one that replaces in place. */
+  lines: external_exports.array(external_exports.string().max(ACTIVITY_LINE_MAX)).max(ACTIVITY_LINES),
+  /** When the harness observed this tail. Its own timestamp, not the heartbeat's: a beat
+   *  that carries an UNCHANGED tail must not make a stalled agent look like it just moved. */
+  at: external_exports.string().datetime()
+});
 var ConnectionSummarySchema = external_exports.object({
   /** The connection = the agent's token id (used to address a request). */
   id: external_exports.string(),
@@ -30247,6 +30424,11 @@ var ConnectionSummarySchema = external_exports.object({
     harnesses: external_exports.array(external_exports.object({ name: external_exports.string(), label: external_exports.string(), status: external_exports.string() })).optional(),
     workspaces: external_exports.array(external_exports.string()).optional()
   }).optional(),
+  /** The tail of this agent's working log, when a harness is driving it — the agent page's
+   *  live strip. Absent for anything the desktop harness isn't running (a hatched identity
+   *  used straight from a terminal emits no work events; the page says so rather than
+   *  drawing an empty box). */
+  activity: AgentActivitySchema.optional(),
   /** True = a provider-managed agent running in the provider's cloud (e.g. Anthropic CMA);
    *  false = a local MCP connection running on the user's computer (Claude Code/Codex/…). */
   managed: external_exports.boolean()
@@ -30315,7 +30497,8 @@ var HandoffSchema = external_exports.object({
   recap: external_exports.boolean().optional()
 });
 var NoteSourceSchema = external_exports.enum(["app", "call"]);
-var NoteStatusSchema = external_exports.enum(["open", "assigned", "done"]);
+var NoteStatusSchema = external_exports.enum(["open", "assigned", "in_progress", "done"]);
+var NoteRepeatSchema = external_exports.enum(["once", "until_done"]);
 var DecisionSchema = external_exports.object({
   id: external_exports.string(),
   /** The note this decision refines; null = recorded on a bare thread (the
@@ -30340,11 +30523,29 @@ var NoteSchema = external_exports.object({
   assignee: external_exports.string().nullable(),
   /** The request thread minted at assignment; null until assigned. */
   parentId: external_exports.string().nullable(),
+  /** REMINDERS (reminders-design.md): the NOT-BEFORE this becomes eligible to ride a
+   *  call — never a deadline, and nothing rings when it passes. Null = "the very next
+   *  call", the right reading of "remind me to…" with no time attached. */
+  //  Defaulted, not required: a Note from an API deploy older than the reminders
+  //  migration has none of these, and the defaults ARE what it means — no not-before,
+  //  one ride, never ridden. Parsing must not fail across a rolling deploy.
+  dueAt: external_exports.string().nullable().default(null),
+  repeat: NoteRepeatSchema.default("once"),
+  /** How many calls have already carried it — the fatigue cap counts rides, not days. */
+  rides: external_exports.number().int().default(0),
+  lastRideAt: external_exports.string().nullable().default(null),
   createdAt: external_exports.string()
 });
 var CreateNoteSchema = external_exports.object({
   /** The intent, in the user's own words. Stored verbatim; the broker only titles it. */
-  text: external_exports.string().min(1).max(4e3)
+  text: external_exports.string().min(1).max(4e3),
+  /** Capture it as a REMINDER — a note assigned to the user themselves, which rides
+   *  their next call instead of being handed to an agent. Everything else about the
+   *  note is identical; this is the one parameter that separates the two. */
+  forMe: external_exports.boolean().optional(),
+  /** The not-before, when the user already said one. Absent = the very next call. */
+  dueAt: external_exports.string().datetime().optional(),
+  repeat: NoteRepeatSchema.optional()
 });
 var RecordDecisionSchema = external_exports.object({
   /** An open decision (from /clarify) to answer. */
@@ -31081,10 +31282,14 @@ async function claimSessions(opts = {}) {
   return (await res.json()).sessions;
 }
 async function heartbeat(runtime, opts = {}) {
+  const body = {
+    ...runtime !== void 0 ? { runtime } : {},
+    ...opts.activity !== void 0 ? { activity: opts.activity } : {}
+  };
   const res = ensureAuthed(await reach(`${BACKEND_URL}/api/presence`, {
     method: "POST",
     headers: { "content-type": "application/json", authorization: `Bearer ${authToken(opts.token)}` },
-    ...runtime !== void 0 ? { body: JSON.stringify({ runtime }) } : {}
+    ...Object.keys(body).length > 0 ? { body: JSON.stringify(body) } : {}
   }));
   if (!res.ok) throw new Error(`heartbeat failed: ${res.status}`);
 }
@@ -31158,6 +31363,12 @@ var ReceiptEventSchema2 = external_exports.enum([
   // the recipient opened it
   "answered",
   // the recipient replied
+  // The recipient TURNED THE RING DOWN — CallKit ended it and no answer was ever tapped.
+  // Written by the phone, on the same door that reports the ring itself, so it exists only
+  // when a ring reached a running app and a person did not take it. That is what separates
+  // it from "a ring with no answer", which our own crashes wrote just as readily and which
+  // is why the responsiveness back-off had to be removed (#1144).
+  "declined",
   "escalated",
   // re-reached at a higher level (re-ring / promote)
   "coalesced",
@@ -31166,8 +31377,14 @@ var ReceiptEventSchema2 = external_exports.enum([
   // deadline passed unanswered
   "woke",
   // the agent was woken for an owed obligation (callback)
-  "gave_up"
+  "gave_up",
   // the budget was spent — stopped re-engaging
+  // The ladder starts over — a silent pickup (the owner's fresh-miss rule, 2026-07-28), a
+  // promote to call, a re-delivery. APPENDED, never a rewind: `ring_step` was a cache of
+  // the escalated-count and a writer rewound it to 0 on every unanswered call (2026-08-24,
+  // nine rings in an hour, `gaveUp` unreachable). A count since the last `restarted` cannot
+  // be rewound by a writer that forgot to advance it.
+  "restarted"
 ]);
 var AttentionSchema2 = external_exports.object({
   urgency: NotifyLevelSchema2,
@@ -31299,7 +31516,7 @@ var NotifyRequestSchema2 = external_exports.object({
   if (r.ask !== void 0) {
     for (const f of ["context", "select", "points"]) {
       if (r[f] !== void 0)
-        ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: [f], message: `the simplified \`ask\` form takes no ${f} \u2014 the broker derives it (use \`needs\` for multi-part asks)` });
+        ctx.addIssue({ code: external_exports.ZodIssueCode.custom, path: [f], message: `the simplified \`ask\` form takes no ${f} \u2014 the broker derives the answer shape from your prose. Drop ${f} and say it in \`ask\` instead ("should I\u2026" for approve/deny, "which of these\u2026" for a pick), passing \`options\` when you're offering concrete alternatives.` });
     }
     return;
   }
@@ -31374,6 +31591,14 @@ var IntentSchema2 = external_exports.object({
    *  about what cannot answer "is the bot looping less this week?". */
   fault: external_exports.enum(["loop", "unanswered", "overridden", "misheard", "slow", "other"]).optional()
 });
+var RideAlongSchema2 = external_exports.object({
+  /** The note this came from — assign/clarify/close it through /api/notes/:id. */
+  noteId: external_exports.string(),
+  /** What to do, in the owner's own words (the note's headline). Never model-rewritten. */
+  text: external_exports.string(),
+  /** The thread to report back on, when the note was dispatched over the request rail. */
+  parentId: external_exports.string().nullable()
+});
 var AwaitItemSchema2 = external_exports.discriminatedUnion("type", [
   external_exports.object({
     type: external_exports.literal("reply"),
@@ -31394,7 +31619,13 @@ var AwaitItemSchema2 = external_exports.discriminatedUnion("type", [
     transcript: external_exports.string().optional(),
     /** Coverage report (#396), when the ask declared `points`: which of them this
      *  answer addressed. Missing points = re-ask or proceed knowingly partial. */
-    covered: external_exports.array(external_exports.string()).optional()
+    covered: external_exports.array(external_exports.string()).optional(),
+    /** Ride-alongs (RideAlongSchema) — pending work for you, attached to the moment you
+     *  became free. Only `reply` and `idle` carry it: those are the two outcomes that
+     *  END a wait. `remind`, `superseded` and `turn` are mid-flight, and handing an
+     *  agent a side-quest while it is still holding the line is how the main thing gets
+     *  dropped. Absent/empty = nothing owed. */
+    also: external_exports.array(RideAlongSchema2).optional()
   }),
   external_exports.object({
     type: external_exports.literal("remind"),
@@ -31429,7 +31660,7 @@ var AwaitItemSchema2 = external_exports.discriminatedUnion("type", [
       acts: external_exports.array(IntentSchema2).nullable().optional()
     })
   }),
-  external_exports.object({ type: external_exports.literal("idle") })
+  external_exports.object({ type: external_exports.literal("idle"), also: external_exports.array(RideAlongSchema2).optional() })
 ]);
 var CallbackTriggerSchema2 = external_exports.enum(["on_done", "on_blocked", "scheduled"]);
 var ScheduleCallbackSchema2 = external_exports.object({
@@ -31460,6 +31691,12 @@ var PendingRepliesSchema2 = external_exports.object({
   pending: external_exports.array(
     external_exports.object({ parentId: external_exports.string(), notificationId: external_exports.string(), createdAt: external_exports.string() })
   ),
+  /** WHO YOU ARE on this account (field report 2026-08-28): the name and device the user
+   *  sees for this session's identity. From inside a session there was no way to find out —
+   *  `pair` with no arguments can HATCH a fresh identity, so it is not a safe probe — and an
+   *  agent that cannot tell which agent it is cannot tell whether work addressed to
+   *  "Reta" was addressed to it. Absent only for a token with no pairing behind it. */
+  you: external_exports.object({ name: external_exports.string(), device: external_exports.string().nullable(), tokenId: external_exports.string() }).optional(),
   /** User-initiated requests addressed to this agent; act on them and reply via
    *  contact on the same parentId. Keeps reappearing until you call
    *  set_task_state on its notificationId. */
@@ -31471,12 +31708,21 @@ var PendingRepliesSchema2 = external_exports.object({
       createdAt: external_exports.string(),
       /** The user seeded this request with a past conversation — call get_thread on it
        *  FIRST and treat the transcript as prior context (#57/#251). */
-      contextParentId: external_exports.string().optional()
+      contextParentId: external_exports.string().optional(),
+      /** STRANDED (field report 2026-08-28): this request was addressed to ANOTHER agent on
+       *  the account — the name here — which has not been seen since it landed, so nobody
+       *  came for it. Handed to you because you are the session that is here. Take it like
+       *  any request (set_task_state claims it, reply with contact on its parentId), and say
+       *  whose it was, because the user chose that agent on purpose. */
+      stranded: external_exports.string().optional()
     })
   ),
   /** Callbacks you owe the user that are now DUE (you said you'd follow up when done,
    *  if blocked, or at a time that has passed). Re-surfaced every sweep until you
    *  fulfill one by calling contact on its parentId. */
+  /** Ride-alongs (RideAlongSchema): notes assigned to this agent that no wake could
+   *  reach. Same array the contact/await replies carry — one queue, every carrier. */
+  also: external_exports.array(RideAlongSchema2).optional(),
   owedCallbacks: external_exports.array(
     external_exports.object({ parentId: external_exports.string(), trigger: CallbackTriggerSchema2, note: external_exports.string() })
   ),
@@ -31512,7 +31758,11 @@ var NotifyResponseSchema2 = external_exports.object({
   status: NotifyStatusSchema2,
   createdAt: external_exports.string().datetime(),
   answer: UserAnswerSchema2.optional(),
-  answeredAt: external_exports.string().datetime().optional()
+  answeredAt: external_exports.string().datetime().optional(),
+  /** Ride-alongs for THIS agent — pending work it should pick up when it's done with
+   *  what it came for. Present on any reply, because an unwakeable agent's only
+   *  reliable moment is one it initiated. Absent/empty = nothing owed. */
+  also: external_exports.array(RideAlongSchema2).optional()
 });
 var NotifyPlanUnitSchema2 = external_exports.object({
   notificationId: external_exports.string(),
@@ -31534,7 +31784,13 @@ var NotifyPlanUnitSchema2 = external_exports.object({
   proposal: external_exports.object({
     select: SelectShapeSchema2,
     options: external_exports.array(external_exports.object({ label: external_exports.string().min(1) })).optional()
-  }).optional()
+  }).optional(),
+  /** What the broker READ this unit as wanting from the human (#952 layer 2): a `decision`
+   *  between alternatives, an `approval` the agent is blocked on, or `knowledge` it just
+   *  needs to know. Reported so the agent can correct a misread the same way it ratifies a
+   *  shape — the read RAISES (a decision always asks) and never silences a question the
+   *  agent declared (#731, #923). */
+  wants: external_exports.enum(["decision", "approval", "knowledge"]).optional()
 });
 var NotifyPlanSchema2 = external_exports.object({
   units: external_exports.array(NotifyPlanUnitSchema2),
@@ -31558,6 +31814,9 @@ var UserResponseSchema2 = external_exports.object({
 });
 var VoiceKeySchema2 = external_exports.enum(["rachel", "george", "jessica", "brian", "lily"]);
 var AgendaTurnSchema2 = external_exports.object({
+  /** Twin coverage (#1089): sibling claim ids this asking turn's answer ALSO settles —
+   *  the planner declares duplicates instead of asking them twice. */
+  coveredIds: external_exports.array(external_exports.string()).optional(),
   /** At most three short spoken sentences. Capped because a turn is a breath: a 1031-char
    *  line went out on 2026-07-28 and the caller could not answer it at all. */
   info: external_exports.array(external_exports.string().min(1)).max(3).default([]),
@@ -31591,6 +31850,7 @@ var AgendaTurnSchema2 = external_exports.object({
    *  on, the claim stays pending; blocking:true on context = hold for a reply. */
   blocking: external_exports.boolean().optional()
 });
+var CLAIM_STALE_MS2 = 30 * 6e4;
 var InboxItemSchema2 = external_exports.object({
   id: external_exports.string(),
   /** The conversation thread + connection this item lives on. Present on the replied
@@ -31610,6 +31870,15 @@ var InboxItemSchema2 = external_exports.object({
    *  (live 2026-08-10, D35). The API already orders by it; this lets a reader that
    *  re-sorts (grouping, filtering) put an arrival back in the order it was written. */
   seq: external_exports.number().int().optional(),
+  /** HOW MANY units the arrival was cut into. A device reads a LENS, never the arrival —
+   *  `/api/inbox` serves `open`, so the units already settled are gone from it — and a client
+   *  counting what it can see is counting what is LEFT. Walking a three-unit ask on the answer
+   *  screen read "1 of 3", then "1 of 2", then no chip at all, each answer having removed the
+   *  only evidence of itself. How big an arrival is, is a fact about the arrival, so the
+   *  server that can still see every row states it. Absent on any row with no `askId`: a
+   *  unit knows WHICH ask it came from and WHERE it sat in it, and how many there were is
+   *  the one part of its own arrival a single row cannot answer. */
+  units: external_exports.number().int().positive().optional(),
   tokenId: external_exports.string().optional(),
   status: NotifyStatusSchema2,
   context: ContextSchema2,
@@ -31630,6 +31899,16 @@ var InboxItemSchema2 = external_exports.object({
    *  while the party called the same dead claim stalled. Absent = no token/no data,
    *  which must never CLAIM stalled. */
   lastSeenAt: external_exports.string().optional(),
+  /** WHEN THE AGENT LAST SAID ANYTHING ABOUT THIS CLAIM — the newest `agent_state` row in
+   *  the `notification_events` ledger (trigger-written since 20260621010000, so every row a
+   *  user can see has one). The age input for `CLAIM_STALE_MS`, and it has to be this rather
+   *  than `createdAt`: a claim is very often picked up long after the row was born — the
+   *  inbox keeps an ANSWERED row visible while the agent works the follow-up, so a question
+   *  asked this morning and claimed a minute ago is eight hours old and one minute into its
+   *  work. Reading the row's birth as the claim's age brands that "No update in 8h" the
+   *  instant the agent picks it up (#997). Absent = pre-trigger row; fall back to
+   *  `createdAt`. */
+  agentStateAt: external_exports.string().datetime().optional(),
   agenda: external_exports.array(AgendaTurnSchema2).optional(),
   /** On a replied detail (#397): the next steps the user attached to the answer
    *  ("call back after lunch") — shown so they can see the commitment was captured. */
@@ -31701,11 +31980,23 @@ var SnoozeRequestSchema2 = external_exports.object({
   requestId: external_exports.string(),
   until: external_exports.string().datetime()
 });
+var APNS_TOKEN_RE2 = /^[0-9a-fA-F]{64}$/;
 var PushTokenSchema2 = external_exports.object({
   voipToken: external_exports.string().min(1).optional(),
   alertToken: external_exports.string().min(1).optional(),
   fcmToken: external_exports.string().min(1).optional(),
   platform: external_exports.enum(["ios", "android"])
+}).superRefine((v, ctx) => {
+  if (v.platform !== "ios") return;
+  for (const field of ["voipToken", "alertToken"]) {
+    const token = v[field];
+    if (token === void 0 || APNS_TOKEN_RE2.test(token)) continue;
+    ctx.addIssue({
+      code: external_exports.ZodIssueCode.custom,
+      path: [field],
+      message: `not an APNs device token (want 64 hex chars, got ${token.length})`
+    });
+  }
 });
 var MissedCallSchema2 = external_exports.enum([
   "retry_10m",
@@ -31756,6 +32047,15 @@ var UserSettingsSchema2 = external_exports.object({
   /** Opt-in to real-phone (PSTN) calls when the app can't ring. Optional, not
    *  defaulted — an older client PATCHing the full object must not clobber it. */
   pstnCalls: external_exports.boolean().optional(),
+  /** The user's IANA timezone (e.g. "America/Bogota"), recorded by the app — it is the
+   *  only party that knows it. REMINDERS are why it exists: "remind me at ten" becomes
+   *  an absolute `due_at` only if we know whose ten. Optional and never defaulted, for
+   *  the same reason `voiceMode` is (a stale client PATCHing the whole object must not
+   *  clobber it) and one more: a GUESSED timezone schedules reminders hours off, and
+   *  that failure reads as the reminder rail being unreliable rather than as a missing
+   *  setting. Absent = a spoken time can't be landed, so the reminder rides the next
+   *  call — honest about what we know. */
+  timezone: external_exports.string().min(1).max(64).optional(),
   /** Account E2EE state (text lane): 'off' (default) = today's plaintext; 'on' =
    *  content is sealed end-to-end between the local agent and the phone. Like
    *  voiceMode, OPTIONAL and NOT defaulted so a stale client PATCHing the full
@@ -31781,6 +32081,15 @@ var HistoryItemSchema2 = external_exports.object({
   /** When you answered the agent's notification (agent→user only). */
   humanAckedAt: external_exports.string().nullable()
 });
+var ACTIVITY_LINES2 = 2;
+var ACTIVITY_LINE_MAX2 = 80;
+var AgentActivitySchema2 = external_exports.object({
+  /** Oldest first, so the newest line is last — the one that replaces in place. */
+  lines: external_exports.array(external_exports.string().max(ACTIVITY_LINE_MAX2)).max(ACTIVITY_LINES2),
+  /** When the harness observed this tail. Its own timestamp, not the heartbeat's: a beat
+   *  that carries an UNCHANGED tail must not make a stalled agent look like it just moved. */
+  at: external_exports.string().datetime()
+});
 var ConnectionSummarySchema2 = external_exports.object({
   /** The connection = the agent's token id (used to address a request). */
   id: external_exports.string(),
@@ -31814,6 +32123,11 @@ var ConnectionSummarySchema2 = external_exports.object({
     harnesses: external_exports.array(external_exports.object({ name: external_exports.string(), label: external_exports.string(), status: external_exports.string() })).optional(),
     workspaces: external_exports.array(external_exports.string()).optional()
   }).optional(),
+  /** The tail of this agent's working log, when a harness is driving it — the agent page's
+   *  live strip. Absent for anything the desktop harness isn't running (a hatched identity
+   *  used straight from a terminal emits no work events; the page says so rather than
+   *  drawing an empty box). */
+  activity: AgentActivitySchema2.optional(),
   /** True = a provider-managed agent running in the provider's cloud (e.g. Anthropic CMA);
    *  false = a local MCP connection running on the user's computer (Claude Code/Codex/…). */
   managed: external_exports.boolean()
@@ -31882,7 +32196,8 @@ var HandoffSchema2 = external_exports.object({
   recap: external_exports.boolean().optional()
 });
 var NoteSourceSchema2 = external_exports.enum(["app", "call"]);
-var NoteStatusSchema2 = external_exports.enum(["open", "assigned", "done"]);
+var NoteStatusSchema2 = external_exports.enum(["open", "assigned", "in_progress", "done"]);
+var NoteRepeatSchema2 = external_exports.enum(["once", "until_done"]);
 var DecisionSchema2 = external_exports.object({
   id: external_exports.string(),
   /** The note this decision refines; null = recorded on a bare thread (the
@@ -31907,11 +32222,29 @@ var NoteSchema2 = external_exports.object({
   assignee: external_exports.string().nullable(),
   /** The request thread minted at assignment; null until assigned. */
   parentId: external_exports.string().nullable(),
+  /** REMINDERS (reminders-design.md): the NOT-BEFORE this becomes eligible to ride a
+   *  call — never a deadline, and nothing rings when it passes. Null = "the very next
+   *  call", the right reading of "remind me to…" with no time attached. */
+  //  Defaulted, not required: a Note from an API deploy older than the reminders
+  //  migration has none of these, and the defaults ARE what it means — no not-before,
+  //  one ride, never ridden. Parsing must not fail across a rolling deploy.
+  dueAt: external_exports.string().nullable().default(null),
+  repeat: NoteRepeatSchema2.default("once"),
+  /** How many calls have already carried it — the fatigue cap counts rides, not days. */
+  rides: external_exports.number().int().default(0),
+  lastRideAt: external_exports.string().nullable().default(null),
   createdAt: external_exports.string()
 });
 var CreateNoteSchema2 = external_exports.object({
   /** The intent, in the user's own words. Stored verbatim; the broker only titles it. */
-  text: external_exports.string().min(1).max(4e3)
+  text: external_exports.string().min(1).max(4e3),
+  /** Capture it as a REMINDER — a note assigned to the user themselves, which rides
+   *  their next call instead of being handed to an agent. Everything else about the
+   *  note is identical; this is the one parameter that separates the two. */
+  forMe: external_exports.boolean().optional(),
+  /** The not-before, when the user already said one. Absent = the very next call. */
+  dueAt: external_exports.string().datetime().optional(),
+  repeat: NoteRepeatSchema2.optional()
 });
 var RecordDecisionSchema2 = external_exports.object({
   /** An open decision (from /clarify) to answer. */
@@ -32690,9 +33023,30 @@ function startSession(opts) {
   };
 }
 
+// src/paigy/activity.ts
+function shortenPaths(s) {
+  return s.replace(/(?<![\w.@+-])(?:\/[\w.@+-]+){3,}/g, (p) => {
+    const parts = p.split("/").filter(Boolean);
+    return `\u2026/${parts.slice(-2).join("/")}`;
+  });
+}
+function workLine(event) {
+  const note = (event.note ?? "").split("\n").find((l) => l.trim()) ?? "";
+  const line = shortenPaths([event.tool.trim(), note.trim()].filter(Boolean).join(" \u2014 ").replace(/\s+/g, " "));
+  return line.length > ACTIVITY_LINE_MAX2 ? `${line.slice(0, ACTIVITY_LINE_MAX2 - 1)}\u2026` : line;
+}
+function pushWork(lines, line) {
+  if (!line || lines[lines.length - 1] === line) return [...lines];
+  return [...lines, line].slice(-ACTIVITY_LINES2);
+}
+function sameTail(a, b) {
+  return a.length === b.length && a.every((l, i) => l === b[i]);
+}
+
 // src/run.ts
 function runHarness(opts) {
   let running = true;
+  let tail = [];
   const state = { ...opts.exclusive ? { exclusive: true } : {} };
   let session = null;
   const asMe = { token: opts.token };
@@ -32722,6 +33076,7 @@ function runHarness(opts) {
     }
     if (event.kind === "work") {
       opts.log(`\u2699 ${event.tool}${event.note ? ` \u2014 ${event.note.split("\n")[0] ?? ""}` : ""}`);
+      tail = pushWork(tail, workLine(event));
       return;
     }
     const { parentId } = await mirror(event, state, deps);
@@ -32729,6 +33084,7 @@ function runHarness(opts) {
     if (event.kind === "turn") opts.log(`${event.role}: ${event.text.split("\n")[0] ?? ""}`);
     if (event.kind === "idle") {
       state.resting = true;
+      tail = [];
       if (endsWithQuestion(event.result)) {
         const local = await opts.localAsk?.question?.(event.result ?? "") ?? null;
         if (local?.trim() && session && running) {
@@ -32766,8 +33122,10 @@ function runHarness(opts) {
       session?.send(text);
     },
     working: () => running && state.resting !== true,
+    tail: () => [...tail],
     stop() {
       running = false;
+      tail = [];
       cancelAsks(state);
       session?.stop();
       session = null;
@@ -32820,6 +33178,12 @@ function resolveWakeDir(pinned, deps) {
 
 // src/host.ts
 var HOST_FILE = join4(homedir5(), ".paigy", "host.json");
+var IDLE_WAKE_MS = 10 * 6e4;
+function wakeAction(live, seenAt, now) {
+  if (!live) return "spawn";
+  if (seenAt === void 0) return "skip";
+  return now - seenAt >= IDLE_WAKE_MS ? "prompt" : "skip";
+}
 function startHost(opts) {
   const runs = /* @__PURE__ */ new Map();
   const asHost = { token: opts.token };
@@ -32875,12 +33239,15 @@ function startHost(opts) {
     }
   }
   const SLOT_HARNESS = { "mcp-agent": "claude", codex: "codex", antigravity: "agy" };
-  const WAKE_PROMPT = "You were woken because Paigy work is waiting for you. This is a fresh session with your existing identity, so you may already have work in flight that you can't remember. Call check_replies FIRST, then get_thread on each conversation it returns and read it before you touch anything: it holds what you were doing, where (a repo or worktree may not be this folder), and what the owner already decided. Then handle what's waiting and follow your paigy instructions to stay in the loop. Speak to the owner at exactly TWO moments: when you are BLOCKED on a decision only they can make (contact with waiting:'hard', the decision as the ask, options if you have real ones), and when you are DONE (one short report: what shipped, how you verified it, anything you flagged). Progress is never a contact \u2014 call set_task_state('in_progress') when you pick work up and the app shows you working; narrate to the terminal, not to the human.";
+  const wakePrompt = (fresh) => "You were woken because Paigy work is waiting for you. " + (fresh ? "This is a fresh session with your existing identity, so you may already have work in flight that you can't remember. " : "You have been running, so some of this may already be yours \u2014 but not what arrived while you were idle. ") + "Call check_replies FIRST, then get_thread on each conversation it returns and read it before you touch anything: it holds what you were doing, where (a repo or worktree may not be this folder), and what the owner already decided. Then handle what's waiting and follow your paigy instructions to stay in the loop. Speak to the owner at exactly TWO moments: when you are BLOCKED on a decision only they can make (contact with waiting:'hard', the decision as the ask, options if you have real ones), and when you are DONE (one short report: what shipped, how you verified it, anything you flagged). Progress is never a contact \u2014 call set_task_state('in_progress') when you pick work up and the app shows you working; narrate to the terminal, not to the human.";
   async function sweepSlots() {
     for (const slot of listSlots()) {
       const harness = SLOT_HARNESS[slot] ?? (slot === "Desktop" ? void 0 : "claude");
       const key = `slot:${slot}`;
-      if (!harness || runs.has(key)) continue;
+      if (!harness) continue;
+      const live = runs.get(key);
+      const action = wakeAction(!!live, published.get(key)?.movedAt, Date.now());
+      if (action === "skip") continue;
       const token = readToken(slot);
       if (!token) continue;
       const workspace = resolveWakeDir(slotIdentity(slot).workspace, opts.wsDeps);
@@ -32888,12 +33255,20 @@ function startHost(opts) {
       const work = await checkReplies({ token }).catch(() => null);
       if (!work || work.requests.length === 0 && work.replies.length === 0) continue;
       const label = slotName(slot) ?? slot;
+      if (live) {
+        const seen = published.get(key);
+        const quiet = seen ? Math.round((Date.now() - seen.movedAt) / 6e4) : 0;
+        live.run.send(wakePrompt(false));
+        if (seen) seen.movedAt = Date.now();
+        opts.log(`\u25B6 re-woke ${label} \u2014 quiet ${quiet}m with work waiting`);
+        continue;
+      }
       const log = (line) => opts.log(`[${label}] ${line}`);
       const run = runHarness({
         harness,
         cwd: workspace,
         mode: "bypass",
-        prompt: WAKE_PROMPT,
+        prompt: wakePrompt(true),
         exclusive: true,
         token,
         // A dead run must not squat the slot — evict so the next wake can respawn.
@@ -32909,6 +33284,27 @@ function startHost(opts) {
       opts.log(`\u25B6 woke ${label} (${harness}) \u2014 work was waiting in ${workspace}`);
     }
   }
+  const ACTIVITY_MS = 2e3;
+  const published = /* @__PURE__ */ new Map();
+  const streamActivity = () => {
+    const publishTail = (token, lines) => {
+      void heartbeat(void 0, { token, activity: { lines, at: (/* @__PURE__ */ new Date()).toISOString() } }).catch(() => {
+      });
+    };
+    for (const [key, r] of runs) {
+      if (!r.token) continue;
+      const lines = r.run.tail();
+      const was = published.get(key);
+      if (was && sameTail(was.lines, lines)) continue;
+      published.set(key, { token: r.token, lines, movedAt: Date.now() });
+      publishTail(r.token, lines);
+    }
+    for (const [key, was] of published) {
+      if (runs.has(key)) continue;
+      published.delete(key);
+      if (was.lines.length > 0) publishTail(was.token, []);
+    }
+  };
   const publish = () => {
     try {
       writeFileSync3(HOST_FILE, JSON.stringify({ pid: process.pid, at: Date.now(), roster: api.roster() }));
@@ -32922,6 +33318,7 @@ function startHost(opts) {
     void sweepSlots();
     publish();
   }, 5e3);
+  const activityTick = setInterval(streamActivity, ACTIVITY_MS);
   const stopSessions = () => {
     for (const { run, label } of runs.values()) {
       run.stop();
@@ -32959,6 +33356,8 @@ function startHost(opts) {
       clearInterval(pulse);
       clearInterval(spawnPoll);
       stopSessions();
+      streamActivity();
+      clearInterval(activityTick);
       try {
         writeFileSync3(HOST_FILE, JSON.stringify({ pid: process.pid, at: 0, roster: [] }));
       } catch {
@@ -32970,74 +33369,38 @@ function startHost(opts) {
 }
 
 // src/cli.ts
-function parseArgs(argv) {
-  const args = { harness: "claude", mode: "bypass", cwd: process.cwd(), doctor: false, host: false, pair: false, service: false, setup: false, grant: [], hatch: null, voice: null, slot: null, identity: null, graceSeconds: 90, prompt: "", handoff: false };
-  const words = [];
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    const next = () => argv[++i];
-    if (arg === "--harness") {
-      const v = next();
-      if (v !== "claude" && v !== "codex" && v !== "agy") return { error: `--harness must be claude, codex, or agy, got ${v ?? "nothing"}` };
-      args.harness = v;
-    } else if (arg === "--mode") {
-      const v = next();
-      if (v !== "bypass" && v !== "ask") return { error: `--mode must be bypass or ask, got ${v ?? "nothing"}` };
-      args.mode = v;
-    } else if (arg === "--cwd") {
-      const v = next();
-      if (!v) return { error: "--cwd needs a directory" };
-      args.cwd = v;
-    } else if (arg === "--doctor") {
-      args.doctor = true;
-    } else if (arg === "--grace") {
-      const v = Number(next());
-      if (!Number.isFinite(v) || v < 0) return { error: "--grace needs seconds (0 = straight to phone)" };
-      args.graceSeconds = v;
-    } else if (arg === "host") {
-      args.host = true;
-    } else if (arg === "pair") {
-      args.pair = true;
-    } else if (arg === "setup") {
-      args.setup = true;
-    } else if (arg === "service") {
-      args.service = true;
-    } else if (arg === "--grant") {
-      const v = next();
-      if (!v) return { error: "--grant needs a folder to allow" };
-      args.grant.push(v);
-    } else if (arg === "handoff") {
-      args.handoff = true;
-    } else if (arg === "hatch") {
-      const v = next();
-      if (!v) return { error: 'hatch needs a name: paigy-harness hatch "Voice bug hunter"' };
-      args.hatch = v;
-    } else if (arg === "--voice") {
-      args.voice = next() ?? null;
-    } else if (arg === "--slot") {
-      args.slot = next() ?? null;
-    } else if (arg === "--identity") {
-      const v = next();
-      if (!v) return { error: "--identity needs a hatched agent's name" };
-      args.identity = v;
-    } else if (arg?.startsWith("--")) {
-      return { error: `unknown flag ${arg}` };
-    } else if (arg) {
-      words.push(arg);
-    }
-  }
-  args.prompt = words.join(" ");
-  if (!args.doctor && !args.handoff && !args.hatch && !args.host && !args.pair && !args.service && !args.setup && !args.prompt) return { error: "a prompt is required (or setup / --doctor / pair / host / service / hatch NAME / handoff)" };
-  return args;
-}
 var STATUS_MARK = { ready: "\u2713", login: "\u25D0", "adapter-missing": "\u25D0", missing: "\u2717" };
 async function main() {
   const parsed = parseArgs(process.argv.slice(2));
   if ("error" in parsed) {
     console.error(`paigy-harness: ${parsed.error}`);
-    console.error("usage: paigy-harness setup | pair | host [--grant DIR]\u2026 | service | hatch NAME [--voice KEY] [--slot SLOT] | handoff | [--harness claude|codex|agy] [--mode bypass|ask] [--cwd DIR] [--identity NAME] [--grace SECONDS] [--doctor] PROMPT\u2026");
+    console.error(USAGE);
     process.exit(2);
   }
+  if (parsed.help) {
+    console.log(USAGE);
+    console.log("");
+    console.log("  setup          pair this machine, set up every agent found here, install the host service");
+    console.log("  pair           pair this machine only (QR / code)");
+    console.log("  host           host sessions your phone launches (--grant DIR to allow a folder)");
+    console.log("  service        install the host as a login service (macOS)");
+    console.log("  enable-tools   allowlist Paigy's tools in Claude Code so they don't prompt each time");
+    console.log("  hatch NAME     mint a sibling identity from this machine's credential");
+    console.log("  handoff        pin this terminal's identity here so your phone can resume it");
+    console.log("  --doctor       report which agent CLIs are installed and ready");
+    console.log("");
+    console.log('Anything else is a PROMPT: paigy-harness --harness codex "fix the tests"');
+    return;
+  }
+  if (parsed.enableTools) {
+    try {
+      execSync(`${ENABLE_TOOLS_COMMAND} --scope ${parsed.scope}`, { stdio: "inherit", shell: "/bin/sh" });
+    } catch {
+      console.error(`Couldn't run it \u2014 try directly: ${ENABLE_TOOLS_COMMAND} --scope ${parsed.scope}`);
+      process.exit(1);
+    }
+    return;
+  }
   if (parsed.doctor) {
     for (const a of detectAll()) {
       console.log(`${STATUS_MARK[a.status]} ${a.label}${a.hint ? ` \u2014 ${a.hint}` : ""}${a.install ? `
@@ -33120,6 +33483,14 @@ async function main() {
       } catch {
       }
     }
+    if (which("claude")) {
+      try {
+        execSync(ENABLE_TOOLS_COMMAND, { stdio: "ignore", shell: "/bin/sh" });
+        console.log("\u2713 Paigy's tools allowlisted in Claude Code (they won't prompt each time)");
+      } catch {
+        console.log(`  allowlist it later with: paigy-harness enable-tools`);
+      }
+    }
     try {
       const settings = join5(homedir6(), ".claude", "settings.json");
       if (which("claude") && existsSync5(settings)) {
@@ -33306,9 +33677,6 @@ async function main() {
   });
 }
 void main();
-export {
-  parseArgs
-};
 /*! Bundled license information:
 
 undici/lib/web/fetch/body.js: