@paigy/harness 0.3.1 → 0.3.2

package/dist/cli.js

@@ -29626,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",
@@ -29634,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,
@@ -29880,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"),
@@ -29900,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"),
@@ -29935,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({
@@ -29966,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. */
@@ -29977,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() })
   ),
@@ -30018,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(),
@@ -30070,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([]),
@@ -30103,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
@@ -30122,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,
@@ -30142,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. */
@@ -30213,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",
@@ -30268,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
@@ -30408,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
@@ -30433,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. */
@@ -31255,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",
@@ -31263,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,
@@ -31471,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"),
@@ -31491,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"),
@@ -31526,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({
@@ -31557,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. */
@@ -31568,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() })
   ),
@@ -31609,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(),
@@ -31661,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([]),
@@ -31694,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
@@ -31713,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,
@@ -31733,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. */
@@ -31804,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",
@@ -31859,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
@@ -31999,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
@@ -32024,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. */
@@ -32962,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 };
@@ -33017,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);
@@ -33030,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.
@@ -33063,7 +33296,7 @@ function startHost(opts) {
       const lines = r.run.tail();
       const was = published.get(key);
       if (was && sameTail(was.lines, lines)) continue;
-      published.set(key, { token: r.token, lines });
+      published.set(key, { token: r.token, lines, movedAt: Date.now() });
       publishTail(r.token, lines);
     }
     for (const [key, was] of published) {

package/dist/main.js

@@ -10959,6 +10959,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",
@@ -10967,8 +10973,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,
@@ -11213,6 +11225,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"),
@@ -11233,7 +11253,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"),
@@ -11268,7 +11294,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({
@@ -11299,6 +11325,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. */
@@ -11310,12 +11342,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() })
   ),
@@ -11351,7 +11392,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(),
@@ -11403,6 +11448,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([]),
@@ -11436,6 +11484,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
@@ -11455,6 +11504,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,
@@ -11475,6 +11533,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. */
@@ -11546,11 +11614,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",
@@ -11601,6 +11681,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
@@ -11741,7 +11830,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
@@ -11766,11 +11856,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. */
@@ -12708,6 +12816,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",
@@ -12716,8 +12830,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,
@@ -12924,6 +13044,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"),
@@ -12944,7 +13072,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"),
@@ -12979,7 +13113,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({
@@ -13010,6 +13144,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. */
@@ -13021,12 +13161,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() })
   ),
@@ -13062,7 +13211,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(),
@@ -13114,6 +13267,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([]),
@@ -13147,6 +13303,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
@@ -13166,6 +13323,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,
@@ -13186,6 +13352,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. */
@@ -13257,11 +13433,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",
@@ -13312,6 +13500,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
@@ -13452,7 +13649,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
@@ -13477,11 +13675,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. */
@@ -14377,6 +14593,12 @@ function hostElsewhere() {
   const s = readHostState();
   return !!s && s.pid !== process.pid;
 }
+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 };
@@ -14432,12 +14654,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);
@@ -14445,12 +14670,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 log2 = (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.
@@ -14478,7 +14711,7 @@ function startHost(opts) {
       const lines = r.run.tail();
       const was = published.get(key);
       if (was && sameTail(was.lines, lines)) continue;
-      published.set(key, { token: r.token, lines });
+      published.set(key, { token: r.token, lines, movedAt: Date.now() });
       publishTail(r.token, lines);
     }
     for (const [key, was] of published) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paigy/harness",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Run Claude Code / Codex on this machine, bridged to Paigy — launchable from your phone.",
   "license": "MIT",
   "type": "module",