pactive 0.0.3-alpha.1 → 0.0.4-alpha.1

package/src/core/config.mjs

@@ -8,11 +8,28 @@ export const CONFIG_SCHEMA = {
   'policy.hourlyLimit': { type: 'number', default: 6, humanGated: true, min: 0 },
   'policy.minIntervalMs': { type: 'number', default: 600000, humanGated: true, min: 0 },
   'policy.cooldownMs': { type: 'number', default: 1800000, humanGated: true, min: 0 },
+  // I64: one fleet-wide ceiling; `0` means "never deliver", not "unlimited".
+  'globalGuard.hourlyLimit': { type: 'number', default: 24, humanGated: true, min: 0 },
 };
 
+/** Keys an assistant may override (I63): the throttling policy, nothing global. */
+export const ASSISTANT_POLICY_KEYS = [
+  'policy.quietStart',
+  'policy.quietEnd',
+  'policy.hourlyLimit',
+  'policy.minIntervalMs',
+  'policy.cooldownMs',
+];
+
 export const config = {
-  get(state, key) {
+  /** `assistantId` reads the assistant's override first, then falls back to the global value. */
+  get(state, key, assistantId) {
     const spec = specOf(key);
+    if (typeof assistantId === 'string' && assistantId !== '') {
+      const leaf = assistantLeaf(key);
+      const override = leaf === null ? undefined : state?.assistants?.[assistantId]?.policy?.[leaf];
+      if (override !== undefined && override !== null) return override;
+    }
     const current = readPath(state, key);
     return current === undefined ? spec.default : current;
   },
@@ -24,10 +41,13 @@ export const config = {
       defaults[key] = spec.default;
       if (spec.humanGated) humanGatedKeys.push(key);
     }
-    return { schema: CONFIG_SCHEMA, defaults, humanGatedKeys };
+    return { schema: CONFIG_SCHEMA, defaults, humanGatedKeys, assistantKeys: [...ASSISTANT_POLICY_KEYS] };
   },
 
-  /** Gated keys only change with an explicit confirmation; without one nothing is written. */
+  /**
+   * Gated keys only change with an explicit confirmation; without one nothing is written.
+   * With `options.assistantId` the value becomes that assistant's override (policy keys only).
+   */
   setHumanGated(state, key, value, options = {}) {
     const spec = specOf(key);
     const confirm = options && options.confirm === true;
@@ -37,11 +57,28 @@ export const config = {
     if (!validValue(spec, value)) {
       return { ok: false, key, reason: 'invalid-value' };
     }
+    const assistantId = typeof options.assistantId === 'string' ? options.assistantId : '';
+    if (assistantId !== '') {
+      const leaf = assistantLeaf(key);
+      if (leaf === null) {
+        return { ok: false, key, reason: 'not-per-assistant', assistantId };
+      }
+      const record = state?.assistants?.[assistantId];
+      if (!record) return { ok: false, key, reason: 'unknown-assistant', assistantId };
+      if (!record.policy || typeof record.policy !== 'object') record.policy = {};
+      record.policy[leaf] = value;
+      return { ok: true, key, value, assistantId };
+    }
     writePath(state, key, value);
     return { ok: true, key, value };
   },
 };
 
+function assistantLeaf(key) {
+  if (!ASSISTANT_POLICY_KEYS.includes(key)) return null;
+  return key.slice('policy.'.length);
+}
+
 function specOf(key) {
   const spec = Object.prototype.hasOwnProperty.call(CONFIG_SCHEMA, key) ? CONFIG_SCHEMA[key] : null;
   if (!spec) {

package/src/core/fleet.mjs

@@ -0,0 +1,80 @@
+// Fleet view: the machine-checkable answer to "which assistant lives in which pane" (I76).
+//
+// This module is deliberately pure — no subprocess, no herdr call. The caller injects live state
+// through `statusOf(binding)`, so `fleet ls` stays readable even when herdr is absent (I78: absent
+// means "status unknown", never a fake `idle`).
+import { assistants } from './assistants.mjs';
+import { ledger } from './lineage.mjs';
+
+/** `delivered|queued|unreachable` events → the most recent one per assistant. */
+export function lastDeliveryByAssistant(events = []) {
+  const out = {};
+  for (const event of Array.isArray(events) ? events : []) {
+    if (!event || typeof event !== 'object') continue;
+    if (!['delivered', 'queued', 'unreachable', 'blocked'].includes(event.event)) continue;
+    const id = typeof event.assistantId === 'string' ? event.assistantId : '';
+    if (id === '') continue;
+    const previous = out[id];
+    const ts = Number.isFinite(event.ts) ? event.ts : 0;
+    if (previous && previous.ts > ts) continue;
+    out[id] = {
+      ts,
+      event: event.event,
+      paneId: event.paneId ?? null,
+      reason: event.reason ?? null,
+      prompt: event.prompt ?? null,
+    };
+  }
+  return out;
+}
+
+/**
+ * One row per assistant: identity + binding + live status + last delivery.
+ * `statusOf(binding)` returns a `herdr agent_status` string or null when unobservable.
+ */
+export function fleetRows(state, options = {}) {
+  const statusOf = typeof options.statusOf === 'function' ? options.statusOf : () => null;
+  const last = options.last ?? {};
+  return assistants.list(state).map((record) => {
+    const pane = record.pane ?? null;
+    const bound = pane !== null;
+    const observed = bound ? statusOf(pane) : null;
+    const delivered = last[record.assistantId] ?? null;
+    return {
+      assistantId: record.assistantId,
+      name: record.name,
+      enabled: record.enabled === true,
+      bound,
+      paneId: pane?.paneId ?? null,
+      agentName: pane?.agentName ?? null,
+      host: pane?.host ?? record.delivery?.host ?? null,
+      surface: pane?.surface ?? null,
+      tabId: pane?.tabId ?? null,
+      boundAt: pane?.boundAt ?? 0,
+      // `null` = not observed (herdr absent, or a degraded pane surface). Never printed as idle.
+      status: observed ?? null,
+      lastDeliveryAt: delivered?.ts ?? 0,
+      lastDeliveryEvent: delivered?.event ?? null,
+      lastDeliveryPaneId: delivered?.paneId ?? null,
+      lastDeliveryReason: delivered?.reason ?? null,
+    };
+  });
+}
+
+/** Read the ledger once and build the "recent delivery" column. */
+export function readLastDeliveries(ledgerFile, limit = 500) {
+  if (typeof ledgerFile !== 'string' || ledgerFile === '') return {};
+  try {
+    return lastDeliveryByAssistant(ledger.tail(ledgerFile, limit));
+  } catch {
+    return {};
+  }
+}
+
+export const fleet = {
+  view(state, options = {}) {
+    const last = options.last ?? readLastDeliveries(options.ledgerFile);
+    return fleetRows(state, { ...options, last });
+  },
+  lastDeliveries: readLastDeliveries,
+};

package/src/core/guard.mjs

@@ -1,5 +1,8 @@
-export const GUARD_REASONS = ['quiet', 'hourly-limit', 'min-interval', 'cooldown'];
+import { defaultAssistantId } from './assistants.mjs';
+
+export const GUARD_REASONS = ['quiet', 'hourly-limit', 'global-limit', 'min-interval', 'cooldown'];
 export const HOUR_WINDOW_MS = 3600000;
+export const GLOBAL_HOURLY_LIMIT_DEFAULT = 24;
 
 /** Quiet hours are local wall clock windows, "HH:MM"; a window may wrap midnight. */
 export function inQuietWindow(quietStart, quietEnd, now) {
@@ -24,14 +27,89 @@ function toMinutes(value) {
   return hours * 60 + minutes;
 }
 
-/** The four gates: quiet window, hourly limit, minimum interval, cooldown. */
-export function checkGuard(state, now = Date.now()) {
+/** Either an assistant id, a name, an assistant record, or nothing (= the default assistant). */
+export function resolveAssistantId(state, assistant) {
+  if (typeof assistant === 'string' && assistant.trim() !== '') {
+    const text = assistant.trim();
+    const table = state?.assistants && typeof state.assistants === 'object' ? state.assistants : {};
+    if (table[text]) return text;
+    const byName = Object.values(table).find((a) => a && a.name === text);
+    if (byName && typeof byName.assistantId === 'string') return byName.assistantId;
+    // An unknown name keeps its own bucket: a typo must never charge the default assistant's budget.
+    return text;
+  }
+  if (assistant && typeof assistant === 'object' && typeof assistant.assistantId === 'string') {
+    return assistant.assistantId;
+  }
+  return defaultAssistantId(state?.identity?.ownerKey ?? '');
+}
+
+/** Per-assistant policy override on top of the global policy; absent keys fall back (I63). */
+export function effectivePolicy(state, assistantId) {
+  const base = state?.policy && typeof state.policy === 'object' ? state.policy : {};
+  const out = { ...base };
+  const record = state?.assistants && typeof state.assistants === 'object' ? state.assistants[assistantId] : null;
+  const override = record && record.policy && typeof record.policy === 'object' ? record.policy : {};
+  for (const [key, value] of Object.entries(override)) {
+    if (value !== undefined && value !== null) out[key] = value;
+  }
+  return out;
+}
+
+function freshGuard() {
+  return { hourWindowStart: 0, hourCount: 0, lastTriggerAt: 0, lastTriggerEpoch: -1 };
+}
+
+/**
+ * The guard bucket of one assistant.
+ * The `default` assistant keeps using `state.guard`: that field IS the schema-v1 single-assistant
+ * counter block, so the default assistant needs no second copy that could drift.
+ */
+export function guardOf(state, assistantId) {
+  if (!state.guard || typeof state.guard !== 'object') state.guard = freshGuard();
+  if (!state.guardByAssistant || typeof state.guardByAssistant !== 'object') state.guardByAssistant = {};
+  const bucket = state.guardByAssistant[assistantId];
+  if (bucket && typeof bucket === 'object') {
+    if (!Number.isFinite(bucket.lastTriggerEpoch)) bucket.lastTriggerEpoch = -1;
+    return bucket;
+  }
+  if (assistantId === defaultAssistantId(state.identity?.ownerKey ?? '')) {
+    if (!Number.isFinite(state.guard.lastTriggerEpoch)) state.guard.lastTriggerEpoch = -1;
+    return state.guard;
+  }
+  const fresh = freshGuard();
+  state.guardByAssistant[assistantId] = fresh;
+  return fresh;
+}
+
+function globalOf(state) {
+  if (!state.globalGuard || typeof state.globalGuard !== 'object') {
+    state.globalGuard = { hourWindowStart: 0, hourCount: 0, hourlyLimit: GLOBAL_HOURLY_LIMIT_DEFAULT };
+  }
+  const g = state.globalGuard;
+  if (!Number.isFinite(g.hourlyLimit)) g.hourlyLimit = GLOBAL_HOURLY_LIMIT_DEFAULT;
+  if (!Number.isFinite(g.hourCount)) g.hourCount = 0;
+  if (!Number.isFinite(g.hourWindowStart)) g.hourWindowStart = 0;
+  return g;
+}
+
+function windowOpen(windowStart, ts) {
+  return !(windowStart > 0 && ts - windowStart >= HOUR_WINDOW_MS);
+}
+
+/**
+ * The gates: quiet window, per-assistant hourly limit, optional interval/cooldown, global ceiling.
+ * `options.skipIntervalGates` is for user-scheduled tasks: min-interval/cooldown protect against
+ * proactive nagging, they must not swallow a reminder the user asked for.
+ */
+export function checkGuard(state, now = Date.now(), assistant, options = {}) {
   const ts = Number.isFinite(now) ? now : Date.now();
-  const policy = state.policy || {};
-  const guard = state.guard || {};
+  const assistantId = resolveAssistantId(state, assistant);
+  const policy = effectivePolicy(state, assistantId);
+  const guard = guardOf(state, assistantId);
 
   if (inQuietWindow(policy.quietStart, policy.quietEnd, ts)) {
-    return { pass: false, reason: 'quiet' };
+    return { pass: false, reason: 'quiet', assistantId };
   }
 
   const limit = Number.isFinite(policy.hourlyLimit) ? policy.hourlyLimit : 6;
@@ -39,57 +117,64 @@ export function checkGuard(state, now = Date.now()) {
   const count = Number.isFinite(guard.hourCount) ? guard.hourCount : 0;
   // The window is only rolled over when it really expired; a count without a
   // window start still counts for the current hour.
-  const windowExpired = windowStart > 0 && ts - windowStart >= HOUR_WINDOW_MS;
-  if (!windowExpired && count >= limit) {
-    return { pass: false, reason: 'hourly-limit' };
+  if (windowOpen(windowStart, ts) && count >= limit) {
+    return { pass: false, reason: 'hourly-limit', assistantId };
   }
 
   const lastTriggerAt = Number.isFinite(guard.lastTriggerAt) ? guard.lastTriggerAt : 0;
-  if (lastTriggerAt > 0) {
+  if (lastTriggerAt > 0 && options.skipIntervalGates !== true) {
     const minIntervalMs = Number.isFinite(policy.minIntervalMs) ? policy.minIntervalMs : 600000;
     if (ts - lastTriggerAt < minIntervalMs) {
-      return { pass: false, reason: 'min-interval' };
+      return { pass: false, reason: 'min-interval', assistantId };
     }
     const cooldownMs = Number.isFinite(policy.cooldownMs) ? policy.cooldownMs : 1800000;
     if (ts - lastTriggerAt < cooldownMs) {
-      return { pass: false, reason: 'cooldown' };
+      return { pass: false, reason: 'cooldown', assistantId };
     }
   }
 
-  return { pass: true, reason: 'idle' };
+  const global = globalOf(state);
+  if (windowOpen(global.hourWindowStart, ts) && global.hourCount >= global.hourlyLimit) {
+    return { pass: false, reason: 'global-limit', assistantId };
+  }
+
+  return { pass: true, reason: 'idle', assistantId };
+}
+
+function bumpWindow(bucket, ts) {
+  const windowStart = Number.isFinite(bucket.hourWindowStart) ? bucket.hourWindowStart : 0;
+  if (windowStart > 0 && ts - windowStart >= HOUR_WINDOW_MS) {
+    bucket.hourWindowStart = ts;
+    bucket.hourCount = 0;
+  } else if (windowStart === 0) {
+    bucket.hourWindowStart = ts;
+  }
+  bucket.hourCount = (Number.isFinite(bucket.hourCount) ? bucket.hourCount : 0) + 1;
 }
 
 /**
  * Reserve the right to trigger once for the current activity epoch.
  * Blocks are reported with a reason; the reservation is recorded in the state.
+ * `options.ignoreEpoch` is for explicit user tasks (two reminders may share one epoch).
  */
-export function reserveTrigger(state, now = Date.now()) {
+export function reserveTrigger(state, now = Date.now(), assistant, options = {}) {
   const ts = Number.isFinite(now) ? now : Date.now();
   const epoch = Number.isFinite(state.epoch) ? state.epoch : 0;
-  if (!state.guard || typeof state.guard !== 'object') {
-    state.guard = { hourWindowStart: 0, hourCount: 0, lastTriggerAt: 0, lastTriggerEpoch: -1 };
-  }
-  const guard = state.guard;
-  if (!Number.isFinite(guard.lastTriggerEpoch)) guard.lastTriggerEpoch = -1;
+  const assistantId = resolveAssistantId(state, assistant);
+  const guard = guardOf(state, assistantId);
 
-  const gate = checkGuard(state, ts);
+  const gate = checkGuard(state, ts, assistantId, options);
   if (!gate.pass) {
-    return { reserved: false, epoch, reason: gate.reason };
+    return { reserved: false, epoch, reason: gate.reason, assistantId };
   }
-  if (guard.lastTriggerEpoch === epoch) {
+  if (options.ignoreEpoch !== true && guard.lastTriggerEpoch === epoch) {
     // one trigger per activity epoch; a new user or agent action opens the next one
-    return { reserved: false, epoch, reason: 'requires-action' };
+    return { reserved: false, epoch, reason: 'requires-action', assistantId };
   }
 
-  const windowStart = Number.isFinite(guard.hourWindowStart) ? guard.hourWindowStart : 0;
-  if (windowStart > 0 && ts - windowStart >= HOUR_WINDOW_MS) {
-    guard.hourWindowStart = ts;
-    guard.hourCount = 0;
-  } else if (windowStart === 0) {
-    guard.hourWindowStart = ts;
-  }
-  guard.hourCount = (Number.isFinite(guard.hourCount) ? guard.hourCount : 0) + 1;
+  bumpWindow(guard, ts);
   guard.lastTriggerAt = ts;
   guard.lastTriggerEpoch = epoch;
-  return { reserved: true, epoch };
+  bumpWindow(globalOf(state), ts);
+  return { reserved: true, epoch, assistantId };
 }

package/src/core/idle.mjs

@@ -1,8 +1,8 @@
-import { checkGuard } from './guard.mjs';
+import { checkGuard, effectivePolicy, resolveAssistantId } from './guard.mjs';
 
 export const IDLE_REASONS = [
   'idle', 'disabled', 'no-control', 'busy', 'threshold',
-  'quiet', 'hourly-limit', 'min-interval', 'cooldown', 'requires-action',
+  'quiet', 'hourly-limit', 'global-limit', 'min-interval', 'cooldown', 'requires-action',
 ];
 
 const POLICY_KEYS = ['quietStart', 'quietEnd', 'hourlyLimit', 'minIntervalMs', 'cooldownMs'];
@@ -10,22 +10,26 @@ const POLICY_KEYS = ['quietStart', 'quietEnd', 'hourlyLimit', 'minIntervalMs', '
 /**
  * Four gates must all open before a proactive prompt is allowed:
  * control returned, agent not busy, activity threshold reached, guard open.
+ * `assistant` (name / id / record) selects whose switch, policy override and guard bucket apply.
  */
-export function evaluateIdle(state, now = Date.now(), policy = {}) {
+export function evaluateIdle(state, now = Date.now(), policy = {}, assistant) {
   const ts = Number.isFinite(now) ? now : Date.now();
   const p = policy && typeof policy === 'object' ? policy : {};
   const idleCfg = { ...(state.idle || {}), ...(p.idle || {}) };
+  const assistantId = resolveAssistantId(state, assistant);
+  const record = state.assistants && typeof state.assistants === 'object' ? state.assistants[assistantId] : null;
 
-  const enabled = firstDefined(p.enabled, p.idleEnabled, idleCfg.enabled, false);
+  // I63: every assistant carries its own switch; without one the legacy single switch applies.
+  const enabled = firstDefined(p.enabled, p.idleEnabled, record ? record.enabled : undefined, idleCfg.enabled, false);
   const thresholdMs = firstDefined(p.idleThresholdMs, p.thresholdMs, idleCfg.thresholdMs, 0);
 
-  const guardState = { ...state, policy: { ...(state.policy || {}) } };
+  const guardState = { ...state, policy: { ...effectivePolicy(state, assistantId) } };
   for (const key of POLICY_KEYS) {
     if (p[key] !== undefined) guardState.policy[key] = p[key];
   }
   if (p.policy && typeof p.policy === 'object') Object.assign(guardState.policy, p.policy);
 
-  const guard = checkGuard(guardState, ts);
+  const guard = checkGuard(guardState, ts, assistantId);
   const gates = {
     control: state.controlReturned === true,
     notBusy: state.busy === false,
@@ -41,7 +45,7 @@ export function evaluateIdle(state, now = Date.now(), policy = {}) {
   else if (!gates.guard) reason = guard.reason;
   else reason = 'idle';
 
-  return { idle: reason === 'idle', reason, gates };
+  return { idle: reason === 'idle', reason, gates, assistantId };
 }
 
 function firstDefined(...values) {
@@ -50,4 +54,3 @@ function firstDefined(...values) {
   }
   return undefined;
 }
-

package/src/core/index.mjs

@@ -5,6 +5,9 @@ export { makeIdentity } from './identity.mjs';
 export { markActivity, markControlReturned, getActivity } from './activity.mjs';
 export { evaluateIdle } from './idle.mjs';
 export { checkGuard, reserveTrigger } from './guard.mjs';
+export { assistants, normalizePane } from './assistants.mjs';
+export { fleet } from './fleet.mjs';
+export { runTick } from './tick.mjs';
 export { schedule } from './scheduler.mjs';
 export { mailbox } from './mailbox.mjs';
 export { ledger } from './lineage.mjs';

package/src/core/scheduler.mjs

@@ -1,3 +1,4 @@
+import { defaultAssistantId } from './assistants.mjs';
 import { pactiveError } from './errors.mjs';
 
 export const TASK_KINDS = ['in', 'at', 'every'];
@@ -38,12 +39,16 @@ export const schedule = {
 
     const owner = spec.owner ?? state.identity?.ownerKey ?? '';
     const id = spec.id ?? `task-${ts}-${(seq += 1)}`;
+    // Every task belongs to exactly one assistant (contract §2 / I65): an unqualified task lands
+    // on the default assistant, never on "whoever happens to be first".
+    const assistantId = spec.assistantId ?? defaultAssistantId(state.identity?.ownerKey ?? '');
 
     const existing = state.tasks.find((t) => t.id === id && t.owner === owner && t.dueAt === dueAt && t.active !== false);
     if (existing) return existing;
 
     const task = {
       id,
+      assistantId,
       kind,
       dueAt,
       owner,
@@ -68,8 +73,11 @@ export const schedule = {
     return state.tasks.length !== before;
   },
 
-  list(state) {
-    return Array.isArray(state.tasks) ? [...state.tasks] : [];
+  /** All tasks, or only one assistant's tasks when `assistantId` is given. */
+  list(state, assistantId) {
+    const all = Array.isArray(state.tasks) ? [...state.tasks] : [];
+    if (typeof assistantId !== 'string' || assistantId === '') return all;
+    return all.filter((t) => t && t.assistantId === assistantId);
   },
 
   /** Returns the tasks that are due now and consumes them (once for "in"/"at"). */

package/src/core/state.mjs

@@ -1,14 +1,31 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import {
+  DEFAULT_ASSISTANT_NAME,
+  defaultAssistantId,
+  makeAssistant,
+  normalizeAssistantTable,
+} from './assistants.mjs';
 import { pactiveError } from './errors.mjs';
 import { ensureDir, withLock } from './lock.mjs';
 import { ledger } from './lineage.mjs';
 
-export const SCHEMA_VERSION = 1;
+/** Schema v2 adds the assistant fleet (contract §2 / I61–I66). */
+export const SCHEMA_VERSION = 2;
+export const LEGACY_SCHEMA_VERSION = 1;
+export const GLOBAL_HOURLY_LIMIT_DEFAULT = 24;
 
 let tmpSeq = 0;
 
+export function defaultGuard() {
+  return { hourWindowStart: 0, hourCount: 0, lastTriggerAt: 0, lastTriggerEpoch: -1 };
+}
+
+export function defaultGlobalGuard() {
+  return { hourWindowStart: 0, hourCount: 0, hourlyLimit: GLOBAL_HOURLY_LIMIT_DEFAULT };
+}
+
 export function defaultState() {
   return {
     schemaVersion: SCHEMA_VERSION,
@@ -27,9 +44,14 @@ export function defaultState() {
       minIntervalMs: 600000,
       cooldownMs: 1800000,
     },
-    // lastTriggerEpoch is the extra field the frozen shape does not carry: the
-    // "one trigger per activity epoch" rule needs the epoch of the last trigger.
-    guard: { hourWindowStart: 0, hourCount: 0, lastTriggerAt: 0, lastTriggerEpoch: -1 },
+    // `guard` stays the guard bucket of the `default` assistant (the schema-v1 shape is
+    // exactly one assistant's counters, so no migration shim is needed for it).
+    guard: defaultGuard(),
+    // Every named assistant gets its own bucket: A's cooldown must not throttle B (I62).
+    guardByAssistant: {},
+    // One fleet-wide ceiling no amount of assistants can bypass (I64).
+    globalGuard: defaultGlobalGuard(),
+    assistants: {},
     tasks: [],
     peers: {},
     outbox: [],
@@ -78,6 +100,42 @@ export function ensureStateDirs(paths) {
   return paths;
 }
 
+function normalizeGuard(raw, fallback) {
+  const guard = { ...fallback, ...(raw && typeof raw === 'object' ? raw : {}) };
+  if (!Number.isFinite(guard.hourWindowStart)) guard.hourWindowStart = 0;
+  if (!Number.isFinite(guard.hourCount)) guard.hourCount = 0;
+  if (!Number.isFinite(guard.lastTriggerAt)) guard.lastTriggerAt = 0;
+  if (!Number.isFinite(guard.lastTriggerEpoch)) guard.lastTriggerEpoch = -1;
+  return guard;
+}
+
+function normalizeGuardTable(raw) {
+  const out = {};
+  if (!raw || typeof raw !== 'object') return out;
+  for (const [key, value] of Object.entries(raw)) {
+    if (typeof key !== 'string' || key === '') continue;
+    out[key] = normalizeGuard(value, defaultGuard());
+  }
+  return out;
+}
+
+function normalizeTasks(raw, fallbackAssistantId) {
+  const list = Array.isArray(raw) ? raw : [];
+  const out = [];
+  for (const task of list) {
+    // A non-object entry is dropped, but the caller can see the count change: the read path
+    // normalises rather than inventing fields on garbage.
+    if (!task || typeof task !== 'object') continue;
+    out.push({
+      ...task,
+      assistantId: typeof task.assistantId === 'string' && task.assistantId
+        ? task.assistantId
+        : fallbackAssistantId,
+    });
+  }
+  return out;
+}
+
 function normalize(raw) {
   const base = defaultState();
   const state = { ...base, ...raw };
@@ -85,9 +143,13 @@ function normalize(raw) {
   state.identity = { ...base.identity, ...(raw.identity || {}) };
   state.idle = { ...base.idle, ...(raw.idle || {}) };
   state.policy = { ...base.policy, ...(raw.policy || {}) };
-  state.guard = { ...base.guard, ...(raw.guard || {}) };
-  if (!Number.isFinite(state.guard.lastTriggerEpoch)) state.guard.lastTriggerEpoch = -1;
-  state.tasks = Array.isArray(raw.tasks) ? raw.tasks : [];
+  state.guard = normalizeGuard(raw.guard, base.guard);
+  state.guardByAssistant = normalizeGuardTable(raw.guardByAssistant);
+  state.globalGuard = { ...base.globalGuard, ...(raw.globalGuard || {}) };
+  if (!Number.isFinite(state.globalGuard.hourlyLimit)) state.globalGuard.hourlyLimit = GLOBAL_HOURLY_LIMIT_DEFAULT;
+  const ownerKey = typeof state.identity.ownerKey === 'string' ? state.identity.ownerKey : '';
+  state.assistants = normalizeAssistantTable(raw.assistants, ownerKey);
+  state.tasks = normalizeTasks(raw.tasks, defaultAssistantId(ownerKey));
   state.peers = raw.peers && typeof raw.peers === 'object' ? raw.peers : {};
   state.outbox = Array.isArray(raw.outbox) ? raw.outbox : [];
   state.busy = raw.busy === true;
@@ -99,6 +161,57 @@ function normalize(raw) {
   return state;
 }
 
+/**
+ * Schema v1 → v2: one single-assistant state becomes the `default` assistant.
+ *
+ * Failure is explicit (I20): a v1 file whose tasks cannot be carried over must raise instead of
+ * being quarantined into an empty state, because "quarantine and start fresh" looks identical to
+ * "the user never had anything".
+ */
+export function migrateStateV1(raw, now = Date.now()) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw pactiveError('STATE_MIGRATION_FAILED', 'schema v1 state is not an object');
+  }
+  if (raw.tasks !== undefined && !Array.isArray(raw.tasks)) {
+    throw pactiveError('STATE_MIGRATION_FAILED', 'schema v1 state has a non-array tasks field; refusing to drop it');
+  }
+  const tasks = Array.isArray(raw.tasks) ? raw.tasks : [];
+  const ownerKey = typeof raw.identity?.ownerKey === 'string' ? raw.identity.ownerKey : '';
+  const id = defaultAssistantId(ownerKey);
+  const assistant = makeAssistant(
+    {
+      assistantId: id,
+      name: DEFAULT_ASSISTANT_NAME,
+      title: DEFAULT_ASSISTANT_NAME,
+      // I15: "installed" is not "enabled" — the migrated assistant inherits the old switch.
+      enabled: raw.idle?.enabled === true,
+      createdAt: Number.isFinite(raw.createdAt) ? raw.createdAt : now,
+    },
+    ownerKey,
+    now,
+  );
+  const migratedTasks = tasks.map((task) => {
+    if (!task || typeof task !== 'object') return task;
+    return { ...task, assistantId: id };
+  });
+  if (migratedTasks.length !== tasks.length) {
+    throw pactiveError('STATE_MIGRATION_FAILED', 'schema v1 tasks could not be carried over without loss');
+  }
+  return {
+    ...raw,
+    schemaVersion: SCHEMA_VERSION,
+    assistants: { [id]: assistant },
+    tasks: migratedTasks,
+    guardByAssistant: {},
+    globalGuard: defaultGlobalGuard(),
+  };
+}
+
+/** True when the state file on disk still speaks schema v1 (the CLI reports it). */
+export function needsMigration(parsed) {
+  return parsed && typeof parsed === 'object' && !Array.isArray(parsed) && parsed.schemaVersion === LEGACY_SCHEMA_VERSION;
+}
+
 export function loadState(target) {
   const paths = toPaths(target);
   let raw;
@@ -108,16 +221,25 @@ export function loadState(target) {
     if (err.code === 'ENOENT') return defaultState();
     throw err;
   }
+  let parsed;
   try {
-    const parsed = JSON.parse(raw);
-    if (!parsed || typeof parsed !== 'object' || parsed.schemaVersion !== SCHEMA_VERSION) {
-      throw pactiveError('STATE_SCHEMA_UNSUPPORTED', `unsupported schemaVersion in ${paths.stateFile}`);
-    }
-    return normalize(parsed);
+    parsed = JSON.parse(raw);
   } catch (err) {
     quarantine(paths, err);
     return defaultState();
   }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    quarantine(paths, { code: 'STATE_SCHEMA_UNSUPPORTED' });
+    return defaultState();
+  }
+  if (parsed.schemaVersion === SCHEMA_VERSION) return normalize(parsed);
+  if (needsMigration(parsed)) {
+    // Migration happens on read (read-only callers such as `status`/`doctor` never write);
+    // the next write persists v2 through saveState.
+    return normalize(migrateStateV1(parsed));
+  }
+  quarantine(paths, { code: 'STATE_SCHEMA_UNSUPPORTED' });
+  return defaultState();
 }
 
 function quarantine(paths, cause) {