pactive 0.0.2-alpha.1 → 0.0.4-alpha.1

package/src/core/assistants.mjs

@@ -0,0 +1,237 @@
+import crypto from 'node:crypto';
+
+import { pactiveError } from './errors.mjs';
+
+/**
+ * Assistants: the fleet of logical proactive helpers that share one state root.
+ *
+ * Assistant ids are `<name>#<ownerKey short hash>`: stable and readable, and a rename
+ * keeps the id (contract §2 / I61 / I65). The `default` assistant is the implicit
+ * single assistant of a schema-v1 state; it is created lazily so a fresh install
+ * lists no assistants until somebody names one.
+ */
+
+export const DEFAULT_ASSISTANT_NAME = 'default';
+
+const POLICY_KEYS = ['hourlyLimit', 'minIntervalMs', 'cooldownMs', 'quietStart', 'quietEnd'];
+
+/** `<name>#<12 hex of sha256(ownerKey)>` — deterministic per owner, stable across restarts. */
+export function assistantIdFor(name, ownerKey = '') {
+  const hash = crypto.createHash('sha256').update(String(ownerKey ?? '')).digest('hex').slice(0, 12);
+  return `${slug(name)}#${hash}`;
+}
+
+export function defaultAssistantId(ownerKey = '') {
+  return assistantIdFor(DEFAULT_ASSISTANT_NAME, ownerKey);
+}
+
+function slug(name) {
+  const text = normalizeName(name, { strict: false });
+  return text.replace(/\s+/g, '-');
+}
+
+function normalizeName(name, options = {}) {
+  const text = typeof name === 'string' ? name.trim() : '';
+  if (text === '') {
+    if (options.strict === false) return DEFAULT_ASSISTANT_NAME;
+    throw pactiveError('ASSISTANT_NAME_REQUIRED', 'an assistant needs a name');
+  }
+  if (text.includes('#')) {
+    throw pactiveError('ASSISTANT_NAME_INVALID', `an assistant name must not contain "#": ${text}`);
+  }
+  return text;
+}
+
+/** Only the keys the user actually set — an absent key falls back to the global policy. */
+function normalizePolicy(raw) {
+  const out = {};
+  if (!raw || typeof raw !== 'object') return out;
+  for (const key of POLICY_KEYS) {
+    if (raw[key] !== undefined && raw[key] !== null) out[key] = raw[key];
+  }
+  return out;
+}
+
+/**
+ * The herdr binding of one assistant (contract §2.1): `{paneId, agentName, host, surface, tabId, boundAt}`.
+ * Anything without a usable `paneId` is "not bound" — a half-written record must not look bound.
+ */
+export function normalizePane(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  const paneId = typeof raw.paneId === 'string' && raw.paneId !== '' ? raw.paneId : null;
+  if (!paneId) return null;
+  return {
+    paneId,
+    agentName: typeof raw.agentName === 'string' && raw.agentName !== '' ? raw.agentName : null,
+    // No host name is invented here: the adapter records which host the pane runs (I6 keeps
+    // src/core host-agnostic), so an unset host stays `null` instead of defaulting to one.
+    host: typeof raw.host === 'string' && raw.host !== '' ? raw.host : null,
+    surface: raw.surface === 'pane' ? 'pane' : raw.surface === 'agent' ? 'agent' : (raw.agentName ? 'agent' : 'pane'),
+    tabId: typeof raw.tabId === 'string' && raw.tabId !== '' ? raw.tabId : null,
+    boundAt: Number.isFinite(raw.boundAt) ? raw.boundAt : 0,
+  };
+}
+
+export function makeAssistant(spec = {}, ownerKey = '', now = Date.now()) {
+  const name = normalizeName(spec.name);
+  const assistantId = typeof spec.assistantId === 'string' && spec.assistantId
+    ? spec.assistantId
+    : assistantIdFor(name, ownerKey);
+  const scope = spec.scope && typeof spec.scope === 'object' ? spec.scope : {};
+  const delivery = spec.delivery && typeof spec.delivery === 'object' ? spec.delivery : {};
+  return {
+    assistantId,
+    name,
+    title: typeof spec.title === 'string' && spec.title.trim() !== '' ? spec.title.trim() : name,
+    role: typeof spec.role === 'string' ? spec.role : '',
+    scope: {
+      projectHash: typeof scope.projectHash === 'string' && scope.projectHash ? scope.projectHash : null,
+      globs: Array.isArray(scope.globs) ? scope.globs.filter((g) => typeof g === 'string' && g !== '') : [],
+    },
+    enabled: spec.enabled === true,
+    policy: normalizePolicy(spec.policy),
+    delivery: {
+      host: typeof delivery.host === 'string' && delivery.host ? delivery.host : null,
+      sessionId: typeof delivery.sessionId === 'string' && delivery.sessionId ? delivery.sessionId : null,
+      fallback: typeof delivery.fallback === 'string' && delivery.fallback ? delivery.fallback : 'outbox',
+    },
+    // I75/I76: the display instance (herdr pane), never the identity. `null` = not bound yet.
+    pane: normalizePane(spec.pane),
+    createdAt: Number.isFinite(spec.createdAt) ? spec.createdAt : now,
+    lastFiredAt: Number.isFinite(spec.lastFiredAt) ? spec.lastFiredAt : 0,
+    firedCount: Number.isFinite(spec.firedCount) ? spec.firedCount : 0,
+  };
+}
+
+/** Tolerant read-side normalisation: a dirty record must not crash the state load. */
+export function normalizeAssistant(raw, ownerKey = '', now = Date.now()) {
+  if (!raw || typeof raw !== 'object') return null;
+  const name = typeof raw.name === 'string' && raw.name.trim() !== '' ? raw.name : DEFAULT_ASSISTANT_NAME;
+  const assistantId = typeof raw.assistantId === 'string' && raw.assistantId ? raw.assistantId : assistantIdFor(name, ownerKey);
+  return makeAssistant({ ...raw, name, assistantId }, ownerKey, now);
+}
+
+export function normalizeAssistantTable(raw, ownerKey = '', now = Date.now()) {
+  const out = {};
+  if (!raw || typeof raw !== 'object') return out;
+  for (const [key, value] of Object.entries(raw)) {
+    const record = normalizeAssistant(value, ownerKey, now);
+    if (!record) continue;
+    out[key] = record;
+  }
+  return out;
+}
+
+function tableOf(state, options = {}) {
+  if (!state.assistants || typeof state.assistants !== 'object') {
+    if (options.init !== true) return {};
+    state.assistants = {};
+  }
+  return state.assistants;
+}
+
+function ownerKeyOf(state) {
+  return typeof state?.identity?.ownerKey === 'string' ? state.identity.ownerKey : '';
+}
+
+function byName(a, b) {
+  return a.name.localeCompare(b.name);
+}
+
+export const assistants = {
+  /** Add one assistant. A duplicate name/id is an explicit error, never a silent overwrite. */
+  add(state, spec = {}, now = Date.now()) {
+    const table = tableOf(state, { init: true });
+    const name = normalizeName(spec.name);
+    const record = makeAssistant({ ...spec, name }, ownerKeyOf(state), now);
+    if (table[record.assistantId]) {
+      throw pactiveError('ASSISTANT_EXISTS', `assistant already exists: ${record.assistantId}`);
+    }
+    const clash = Object.values(table).find((a) => a && a.name === name);
+    if (clash) throw pactiveError('ASSISTANT_NAME_TAKEN', `assistant name already taken: ${name}`);
+    table[record.assistantId] = record;
+    return record;
+  },
+
+  list(state) {
+    return Object.values(tableOf(state)).filter((a) => a && typeof a === 'object').sort(byName);
+  },
+
+  /** Resolve by exact id, then by name. Unknown → null (the caller decides the exit code). */
+  resolve(state, ref) {
+    const text = typeof ref === 'string' ? ref.trim() : '';
+    if (text === '') return null;
+    const table = tableOf(state);
+    if (table[text]) return table[text];
+    return Object.values(table).find((a) => a && a.name === text) ?? null;
+  },
+
+  get(state, ref) {
+    return assistants.resolve(state, ref);
+  },
+
+  setEnabled(state, ref, enabled) {
+    const record = assistants.resolve(state, ref);
+    if (!record) return null;
+    record.enabled = enabled === true;
+    return record;
+  },
+
+  /** Bind one assistant to one herdr pane (I79: the caller replaces, never adds a second pane). */
+  bindPane(state, ref, binding, now = Date.now()) {
+    const record = assistants.resolve(state, ref);
+    if (!record) return null;
+    const pane = normalizePane({ ...binding, boundAt: Number.isFinite(binding?.boundAt) ? binding.boundAt : now });
+    if (!pane) return null;
+    record.pane = pane;
+    return record;
+  },
+
+  /** Drop the binding only — the assistant, its tasks and its ledger history stay (I75). */
+  unbindPane(state, ref) {
+    const record = assistants.resolve(state, ref);
+    if (!record) return null;
+    record.pane = null;
+    return record;
+  },
+
+  /** Remove the assistant AND its tasks (I65: no orphans). The ledger keeps the history. */
+  remove(state, ref) {
+    const table = tableOf(state, { init: true });
+    const record = assistants.resolve(state, ref);
+    if (!record) return null;
+    const id = record.assistantId;
+    delete table[id];
+    if (state.guardByAssistant && typeof state.guardByAssistant === 'object') delete state.guardByAssistant[id];
+    const before = Array.isArray(state.tasks) ? state.tasks.length : 0;
+    state.tasks = (Array.isArray(state.tasks) ? state.tasks : []).filter((t) => t && t.assistantId !== id);
+    return { removed: record, tasks: before - state.tasks.length };
+  },
+
+  /** Rename keeps the id: state, ledger history and tasks stay bound to the same assistant. */
+  rename(state, ref, newName) {
+    const table = tableOf(state, { init: true });
+    const record = assistants.resolve(state, ref);
+    if (!record) return null;
+    const name = normalizeName(newName);
+    const clash = Object.values(table).find((a) => a && a.assistantId !== record.assistantId && a.name === name);
+    if (clash) throw pactiveError('ASSISTANT_NAME_TAKEN', `assistant name already taken: ${name}`);
+    record.name = name;
+    if (!record.title || record.title === ref) record.title = name;
+    return record;
+  },
+
+  /** The implicit `default` assistant, created on first use (never enabled silently). */
+  ensureDefault(state, now = Date.now()) {
+    const existing = assistants.resolve(state, DEFAULT_ASSISTANT_NAME);
+    if (existing) return existing;
+    const table = tableOf(state, { init: true });
+    const record = makeAssistant({ name: DEFAULT_ASSISTANT_NAME }, ownerKeyOf(state), now);
+    table[record.assistantId] = record;
+    return record;
+  },
+
+  defaultId(state) {
+    return defaultAssistantId(ownerKeyOf(state));
+  },
+};

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';