@gmickel/gno 2.4.0 → 2.6.0

package/src/sessions/automation.ts

@@ -0,0 +1,1169 @@
+/**
+ * Opt-in session automation: owner profile management, host-hook admission,
+ * and the one run path shared by daemon drains and explicit run-now.
+ *
+ * Hooks and schedule ticks only mark a profile pending (see
+ * automation-state); the import itself is always the manual importer
+ * (SessionsService.import) over the profile's registered sources, so
+ * parsing, redaction, routing and checkpoints have one implementation.
+ * Nothing here enables itself: every trigger is switched on by an explicit
+ * owner call, and every run rechecks the owner config first.
+ *
+ * @module src/sessions/automation
+ */
+
+// node:fs/promises mkdir/stat: directory structure ops without Bun equivalents.
+import { mkdir, stat } from "node:fs/promises";
+// node:path: no Bun path utilities.
+import { isAbsolute, join, resolve } from "node:path";
+
+import type { Config } from "../config/types";
+import type { SqliteAdapter } from "../store/sqlite/adapter";
+import type { SessionAutomationProfile, SessionsConfig } from "./config";
+import type { SessionsServiceDeps } from "./service";
+
+import { getIndexDbPath } from "../app/constants";
+import { loadConfig } from "../config";
+import { applyConfigFileChange } from "../core/config-mutation";
+import { acquireWriteLock } from "../core/file-lock";
+import { SESSION_STATE_DIRNAME } from "./archive";
+import {
+  admit,
+  type AutomationState,
+  beginRun,
+  canStart,
+  classifyRunError,
+  clearPending,
+  finishRun,
+  HOOK_ADMISSION_DEADLINE_MS,
+  isPending,
+  isProcessAlive,
+  isRunLive,
+  loadAutomationState,
+  mutateAutomationState,
+  ownProfile,
+  ownsRun,
+  profileState,
+  recoverInterrupted,
+  type RunFailureClass,
+  scheduleTick,
+  type StartedRun,
+  type StateWriter,
+  unblock,
+} from "./automation-state";
+import {
+  automationCadenceMs,
+  daemonState,
+  profileCollections,
+  profileLimit,
+  profileRetries,
+  scheduleRunnable,
+} from "./automation-status";
+import { canonicalConfigPath, assertSessionBinding } from "./binding";
+import {
+  buildClaudeHookCommand,
+  defaultClaudeSettingsPath,
+  type HookIdentity,
+  inspectClaudeHook,
+  installClaudeHook,
+  removeClaudeHook,
+} from "./claude-hook";
+import {
+  SESSION_HOOK_HARNESSES,
+  SessionAutomationProfileSchema,
+  type SessionHookHarness,
+} from "./config";
+import { importInChildProcess } from "./import-child";
+import { SessionsService } from "./service";
+import { canonicalPath } from "./sources";
+import { importLockPath } from "./state";
+import {
+  type SessionAutomationRunResult,
+  type SessionImportReceipt,
+  type SessionRunRecord,
+  SessionsError,
+  type SessionTriggerKind,
+} from "./types";
+
+export interface AutomationContext {
+  /** Archive config path (the config the hook and daemon are bound to). */
+  configPath: string;
+  indexName: string;
+  env?: NodeJS.ProcessEnv;
+  now?: () => Date;
+}
+
+export interface SessionAutomationPreview {
+  schemaVersion: "1";
+  profileId: string;
+  configPath: string;
+  index: string;
+  archiveRoot: string;
+  sources: Array<{
+    id: string;
+    harness: string | null;
+    path: string | null;
+    available: boolean;
+    collection: string | null;
+    projects: Array<{ prefix: string; collection: string }>;
+  }>;
+  collections: string[];
+  hook: {
+    harness: SessionHookHarness;
+    enabled: boolean;
+    settings: string;
+    command: string;
+    installed: boolean | null;
+  };
+  schedule: { enabled: boolean; cadence: string | null; minimum: "1m" };
+  limit: number;
+  retries: number;
+  daemon: { state: "running" | "not_running" | "stale"; command: string };
+  notes: string[];
+}
+
+export interface SessionAutomationChange {
+  schemaVersion: "1";
+  profileId: string;
+  hook: { enabled: boolean; entriesRemoved: number } | null;
+  schedule: { enabled: boolean } | null;
+  /** Admitted work that was cleared because its trigger was switched off. */
+  pendingCleared: boolean;
+  /** A run already in progress finishes (bounded by the limit); nothing new starts. */
+  running: { startedAt: string } | null;
+  removed: boolean;
+  warnings: string[];
+}
+
+const nowOf = (ctx: AutomationContext): Date => ctx.now?.() ?? new Date();
+
+/**
+ * SQLite writer contention (in this process or reported by an import child)
+ * is a busy archive, retried with backoff, not a runtime error.
+ */
+function isIndexLockContention(error: unknown): boolean {
+  if (typeof error !== "object" || error === null) return false;
+  const { code, message, cause } = error as {
+    code?: unknown;
+    message?: unknown;
+    cause?: unknown;
+  };
+  if (code === "SQLITE_BUSY" || code === "SQLITE_LOCKED") return true;
+  if (
+    typeof message === "string" &&
+    /database is locked|SQLITE_BUSY/i.test(message)
+  ) {
+    return true;
+  }
+  return cause !== undefined && cause !== error && isIndexLockContention(cause);
+}
+
+async function loadArchive(
+  ctx: AutomationContext
+): Promise<{ config: Config; sessions: SessionsConfig }> {
+  const loaded = await loadConfig(ctx.configPath);
+  if (!loaded.ok) {
+    throw new SessionsError(
+      "SESSIONS_NOT_CONFIGURED",
+      "The session archive config could not be loaded."
+    );
+  }
+  if (!loaded.value.sessions) {
+    throw new SessionsError(
+      "SESSIONS_NOT_CONFIGURED",
+      "No session archive is configured for this config."
+    );
+  }
+  await assertSessionBinding({
+    config: loaded.value,
+    configPath: ctx.configPath,
+    indexName: ctx.indexName,
+    dbPath: getIndexDbPath(ctx.indexName),
+  });
+  return { config: loaded.value, sessions: loaded.value.sessions };
+}
+
+const unknownProfile = (id: string): SessionsError =>
+  new SessionsError(
+    "SESSIONS_UNKNOWN_PROFILE",
+    `Unknown automation profile "${id}".`
+  );
+
+function findProfile(
+  sessions: SessionsConfig,
+  id: string
+): SessionAutomationProfile {
+  const profile = sessions.automation?.find((item) => item.id === id);
+  if (!profile) {
+    throw new SessionsError(
+      "SESSIONS_UNKNOWN_PROFILE",
+      `Unknown automation profile "${id}". Configured: ${(sessions.automation ?? []).map((item) => item.id).join(", ") || "(none)"}.`
+    );
+  }
+  return profile;
+}
+
+async function hookIdentity(
+  ctx: AutomationContext,
+  profileId: string
+): Promise<HookIdentity> {
+  return {
+    configPath: await canonicalConfigPath(ctx.configPath),
+    indexName: ctx.indexName,
+    profileId,
+  };
+}
+
+function validCadence(cadence: string): string {
+  if (automationCadenceMs(cadence) === null) {
+    throw new SessionsError(
+      "SESSIONS_INVALID_INPUT",
+      `Cadence "${cadence}" is invalid: use <n>s|m|h|d between 1m and 30d (elapsed time, e.g. 30m or 6h).`
+    );
+  }
+  return cadence;
+}
+
+/** Create the state directory under an existing archive root. */
+async function ensureStateDir(archiveRoot: string): Promise<void> {
+  const root = await stat(archiveRoot).catch(() => null);
+  if (!root?.isDirectory()) {
+    throw new SessionsError(
+      "SESSIONS_SOURCE_UNAVAILABLE",
+      "The session archive destination is missing; recreate it with gno sessions init."
+    );
+  }
+  await mkdir(join(archiveRoot, SESSION_STATE_DIRNAME), { recursive: true });
+}
+
+async function stateDirExists(archiveRoot: string): Promise<boolean> {
+  const dir = await stat(join(archiveRoot, SESSION_STATE_DIRNAME)).catch(
+    () => null
+  );
+  return dir?.isDirectory() === true;
+}
+
+type ProfileEdit = (
+  profile: SessionAutomationProfile | undefined,
+  sessions: SessionsConfig
+) => SessionAutomationProfile | null;
+
+/** Apply one profile change to the owner config under the config lock. */
+async function editProfile(
+  ctx: AutomationContext,
+  id: string,
+  edit: ProfileEdit
+): Promise<SessionsConfig> {
+  const result = await applyConfigFileChange(
+    { configPath: ctx.configPath },
+    (config) => {
+      const sessions = config.sessions;
+      if (!sessions) {
+        return {
+          ok: false,
+          code: "SESSIONS_NOT_CONFIGURED",
+          error: "No session archive is configured for this config.",
+        };
+      }
+      const profiles = sessions.automation ?? [];
+      let next: SessionAutomationProfile | null;
+      try {
+        next = edit(
+          profiles.find((item) => item.id === id),
+          sessions
+        );
+      } catch (error) {
+        if (!(error instanceof SessionsError)) throw error;
+        return { ok: false, code: error.code, error: error.message };
+      }
+      const others = profiles.filter((item) => item.id !== id);
+      const automation = next
+        ? profiles.some((item) => item.id === id)
+          ? profiles.map((item) => (item.id === id ? next : item))
+          : [...profiles, next]
+        : others;
+      if (automation.length > 16) {
+        return {
+          ok: false,
+          code: "SESSIONS_INVALID_INPUT",
+          error: "At most 16 automation profiles per archive.",
+        };
+      }
+      const { automation: _drop, ...rest } = sessions;
+      return {
+        ok: true,
+        config: {
+          ...config,
+          sessions: automation.length > 0 ? { ...rest, automation } : rest,
+        },
+      };
+    }
+  );
+  if (!result.ok) {
+    const code = (
+      result.code.startsWith("SESSIONS_")
+        ? result.code
+        : "SESSIONS_INVALID_INPUT"
+    ) as SessionsError["code"];
+    throw new SessionsError(code, result.error);
+  }
+  return result.config.sessions as SessionsConfig;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Owner management (local surfaces only)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface SetProfileInput {
+  id: string;
+  sources: string[];
+  cadence?: string;
+  limit?: number;
+  retries?: number;
+}
+
+/**
+ * Create or reconfigure a profile. Triggers keep their current state; a new
+ * profile starts with every trigger off.
+ */
+export async function setAutomationProfile(
+  ctx: AutomationContext,
+  input: SetProfileInput
+): Promise<SessionAutomationPreview> {
+  if (input.cadence !== undefined) validCadence(input.cadence);
+  // Binding first: a mismatched pair must not change the archive config.
+  const { sessions: current } = await loadArchive(ctx);
+  await editProfile(ctx, input.id, (existing, sessions) => {
+    for (const sourceId of input.sources) {
+      if (!sessions.sources.some((source) => source.id === sourceId)) {
+        throw new SessionsError(
+          "SESSIONS_UNKNOWN_SOURCE",
+          `Unknown session source "${sourceId}". Register it first with gno sessions source add.`
+        );
+      }
+    }
+    const candidate = {
+      ...existing,
+      id: input.id,
+      sources: input.sources,
+      ...(input.cadence !== undefined
+        ? {
+            schedule: {
+              enabled: existing?.schedule?.enabled ?? false,
+              cadence: input.cadence,
+            },
+          }
+        : {}),
+      ...(input.limit !== undefined ? { limit: input.limit } : {}),
+      ...(input.retries !== undefined ? { retries: input.retries } : {}),
+    };
+    const parsed = SessionAutomationProfileSchema.safeParse(candidate);
+    if (!parsed.success) {
+      throw new SessionsError(
+        "SESSIONS_INVALID_INPUT",
+        `Invalid automation profile: ${parsed.error.issues.map((issue) => `${issue.path.join(".") || "profile"}: ${issue.message}`).join("; ")}`
+      );
+    }
+    return parsed.data;
+  });
+  await settleState(ctx, current, input.id, unblock);
+  return previewAutomationProfile(ctx, input.id);
+}
+
+/** What a profile would run: sources, destinations, triggers, prerequisites. */
+export async function previewAutomationProfile(
+  ctx: AutomationContext,
+  id: string,
+  options: { settings?: string } = {}
+): Promise<SessionAutomationPreview> {
+  const { sessions } = await loadArchive(ctx);
+  const profile = findProfile(sessions, id);
+  const identity = await hookIdentity(ctx, id);
+  const settings =
+    options.settings ??
+    profile.hook?.settings ??
+    defaultClaudeSettingsPath(ctx.env);
+  const { state } = await loadAutomationState(sessions.archiveRoot);
+  const daemon = daemonState(state.daemon, nowOf(ctx));
+  const sources = await Promise.all(
+    profile.sources.map(async (sourceId) => {
+      const source = sessions.sources.find((item) => item.id === sourceId);
+      return {
+        id: sourceId,
+        harness: source?.harness ?? null,
+        path: source?.path ?? null,
+        available: source ? (await canonicalPath(source.path)) !== null : false,
+        collection: source?.collection ?? null,
+        projects: source?.projects ?? [],
+      };
+    })
+  );
+  const configPath = identity.configPath;
+  const daemonCommand = `gno --config ${configPath} --index ${ctx.indexName} daemon`;
+  const notes: string[] = [];
+  if (profile.schedule?.enabled && !scheduleRunnable(profile)) {
+    notes.push(
+      `warning: cadence "${profile.schedule.cadence}" is invalid (use <n>s|m|h|d, 1m to 30d); the schedule is off and does not run until you fix it with sessions automation set ${id} --source … --cadence 30m.`
+    );
+  }
+  if (!profile.hook?.enabled && !profile.schedule?.enabled) {
+    notes.push(
+      `Nothing runs automatically until you enable a trigger: gno --config ${configPath} --index ${ctx.indexName} sessions automation enable ${id} --hook claude-code and/or --schedule --cadence <n>s|m|h|d.`
+    );
+  }
+  notes.push(
+    `Hooks only mark this profile pending; imports run in \`${daemonCommand}\` (currently ${daemon === "running" ? "running" : "not running: no daemon"}) or with \`sessions automation run ${id}\`. GNO never installs or starts a service.`,
+    "Schedules use elapsed time and tick only while that daemon runs; `gno serve` never runs them.",
+    "Imports use each source's registered collection and project mappings; hooks cannot add sources or change destinations."
+  );
+  if (sources.some((source) => source.harness === null)) {
+    notes.push(
+      "A selected source is no longer registered; runs fail until the profile is corrected."
+    );
+  }
+  return {
+    schemaVersion: "1",
+    profileId: id,
+    configPath,
+    index: ctx.indexName,
+    archiveRoot: sessions.archiveRoot,
+    sources,
+    collections: profileCollections(sessions, profile),
+    hook: {
+      harness: "claude-code",
+      enabled: profile.hook?.enabled === true,
+      settings,
+      command: buildClaudeHookCommand(identity),
+      installed: await inspectClaudeHook(settings, identity),
+    },
+    schedule: {
+      // Effective state, as in status: an invalid cadence never runs.
+      enabled: scheduleRunnable(profile),
+      cadence: profile.schedule?.cadence ?? null,
+      minimum: "1m",
+    },
+    limit: profileLimit(profile),
+    retries: profileRetries(profile),
+    daemon: { state: daemon, command: daemonCommand },
+    notes,
+  };
+}
+
+export interface EnableInput {
+  hook?: { harness: string; settings?: string };
+  schedule?: { cadence?: string };
+}
+
+/** Explicitly switch on a hook and/or the daemon schedule for one profile. */
+export async function enableAutomation(
+  ctx: AutomationContext,
+  id: string,
+  input: EnableInput
+): Promise<SessionAutomationPreview> {
+  if (!input.hook && !input.schedule) {
+    throw new SessionsError(
+      "SESSIONS_INVALID_INPUT",
+      "Choose what to enable: --hook claude-code and/or --schedule --cadence <n>s|m|h|d."
+    );
+  }
+  const { sessions } = await loadArchive(ctx);
+  const profile = findProfile(sessions, id);
+  let settings: string | undefined;
+  if (input.hook) {
+    const harness = input.hook.harness;
+    if (!(SESSION_HOOK_HARNESSES as readonly string[]).includes(harness)) {
+      throw new SessionsError(
+        "SESSIONS_UNSUPPORTED_INTEGRATION",
+        `No verified hook for "${harness}". Supported: ${SESSION_HOOK_HARNESSES.join(", ")}. Other harnesses import manually or on a daemon schedule.`
+      );
+    }
+    const harnesses = profile.sources.map(
+      (sourceId) =>
+        sessions.sources.find((source) => source.id === sourceId)?.harness
+    );
+    if (!harnesses.includes("claude-code")) {
+      throw new SessionsError(
+        "SESSIONS_INVALID_INPUT",
+        "The Claude Code hook needs a registered claude-code source in the profile."
+      );
+    }
+    settings =
+      input.hook.settings ??
+      profile.hook?.settings ??
+      defaultClaudeSettingsPath(ctx.env);
+    if (!isAbsolute(settings)) {
+      throw new SessionsError(
+        "SESSIONS_INVALID_INPUT",
+        "The Claude Code settings path must be absolute."
+      );
+    }
+    settings = resolve(settings);
+    // Only the documented default location may be created; any other file
+    // must already exist as a settings file the owner names explicitly.
+    const isDefault = settings === resolve(defaultClaudeSettingsPath(ctx.env));
+    if (input.hook.settings !== undefined && !isDefault) {
+      const file = await stat(settings).catch(() => null);
+      if (!file?.isFile()) {
+        throw new SessionsError(
+          "SESSIONS_INVALID_INPUT",
+          "--settings must name an existing Claude Code settings file; only the default settings.json is created when missing."
+        );
+      }
+    }
+  }
+  let cadence: string | undefined;
+  if (input.schedule) {
+    const requested = input.schedule.cadence ?? profile.schedule?.cadence;
+    if (!requested) {
+      throw new SessionsError(
+        "SESSIONS_INVALID_INPUT",
+        "Scheduling needs an explicit elapsed cadence: --cadence <n>s|m|h|d (at least 1m)."
+      );
+    }
+    cadence = validCadence(requested);
+  }
+  await ensureStateDir(sessions.archiveRoot);
+  const cadenceMs = cadence ? automationCadenceMs(cadence) : null;
+  const identity = await hookIdentity(ctx, id);
+  // Install, record and state change under the marker lock that remove also
+  // holds, so a concurrent remove never leaves an owned entry behind.
+  await mutateAutomationState(sessions.archiveRoot, async (state) => {
+    const current = findProfile((await loadArchive(ctx)).sessions, id);
+    if (settings) {
+      const previous = current.hook?.settings;
+      if (previous && resolve(previous) !== settings) {
+        // Moving to another settings file: remove the old owned entry first
+        // (fails closed), so no untracked integration keeps firing.
+        await removeClaudeHook(previous, identity);
+      }
+      // Install before recording: a settings file that cannot be edited
+      // leaves the profile unchanged.
+      await installClaudeHook(settings, identity);
+    }
+    await editProfile(ctx, id, (existing) => {
+      if (!existing) throw unknownProfile(id);
+      return {
+        ...existing,
+        ...(settings
+          ? {
+              hook: {
+                harness: "claude-code" as const,
+                enabled: true,
+                settings,
+              },
+            }
+          : {}),
+        ...(cadence ? { schedule: { enabled: true, cadence } } : {}),
+      };
+    });
+    // Enabling is an owner action: it clears a block awaiting correction.
+    const existing = ownProfile(state, id);
+    if (existing) unblock(existing);
+    // Like the findings pass: the first scheduled run is one cadence away.
+    if (cadenceMs !== null) {
+      const run = profileState(state, id);
+      run.nextDueAt = new Date(nowOf(ctx).getTime() + cadenceMs).toISOString();
+    }
+  });
+  return previewAutomationProfile(ctx, id);
+}
+
+/**
+ * Drop admitted work of switched-off trigger kinds; manual run requests and
+ * kinds still enabled stay pending.
+ */
+function dropTriggers(
+  run: ReturnType<typeof profileState>,
+  kinds: SessionTriggerKind[]
+): boolean {
+  if (!isPending(run)) return false;
+  const remaining = run.pendingTriggers.filter((kind) => !kinds.includes(kind));
+  if (remaining.length > 0) {
+    run.pendingTriggers = remaining;
+    return false;
+  }
+  clearPending(run);
+  return true;
+}
+
+/** Pause: switch triggers off, uninstall the owned hook entry, clear pending. */
+export async function disableAutomation(
+  ctx: AutomationContext,
+  id: string,
+  which: { hook?: boolean; schedule?: boolean } = {}
+): Promise<SessionAutomationChange> {
+  const both = which.hook === undefined && which.schedule === undefined;
+  const hook = both || which.hook === true;
+  const schedule = both || which.schedule === true;
+  const { sessions } = await loadArchive(ctx);
+  const profile = findProfile(sessions, id);
+  // Config first: a hook that fires from now on sees the trigger disabled.
+  await editProfile(ctx, id, (existing) => {
+    if (!existing) throw unknownProfile(id);
+    return {
+      ...existing,
+      ...(hook && existing.hook
+        ? { hook: { ...existing.hook, enabled: false } }
+        : {}),
+      ...(schedule && existing.schedule
+        ? { schedule: { ...existing.schedule, enabled: false } }
+        : {}),
+    };
+  });
+  const warnings: string[] = [];
+  let entriesRemoved = 0;
+  if (hook && profile.hook) {
+    try {
+      entriesRemoved = (
+        await removeClaudeHook(
+          profile.hook.settings,
+          await hookIdentity(ctx, id)
+        )
+      ).removed;
+    } catch (error) {
+      warnings.push(
+        `The hook is disabled, but its entry could not be removed from the Claude Code settings: ${(error as Error).message}`
+      );
+    }
+  }
+  const settled = await settleState(ctx, sessions, id, (run) => {
+    if (schedule) run.nextDueAt = null;
+    const kinds: SessionTriggerKind[] = [
+      ...(hook ? (["hook"] as const) : []),
+      ...(schedule ? (["schedule"] as const) : []),
+    ];
+    return dropTriggers(run, kinds);
+  });
+  return {
+    schemaVersion: "1",
+    profileId: id,
+    hook: hook && profile.hook ? { enabled: false, entriesRemoved } : null,
+    schedule: schedule && profile.schedule ? { enabled: false } : null,
+    pendingCleared: settled.value ?? false,
+    running: settled.running,
+    removed: false,
+    warnings,
+  };
+}
+
+async function settleState<T>(
+  ctx: AutomationContext,
+  sessions: SessionsConfig,
+  id: string,
+  change: (run: ReturnType<typeof profileState>) => T
+): Promise<{ value: T | null; running: { startedAt: string } | null }> {
+  if (!(await stateDirExists(sessions.archiveRoot))) {
+    return { value: null, running: null };
+  }
+  return mutateAutomationState(sessions.archiveRoot, (state) => {
+    const run = ownProfile(state, id);
+    if (!run) return { value: null, running: null };
+    const value = change(run);
+    return {
+      value,
+      running: isRunLive(run.running, nowOf(ctx))
+        ? { startedAt: run.running!.startedAt }
+        : null,
+    };
+  });
+}
+
+/** Uninstall owned integrations and delete the profile. Archives stay. */
+export async function removeAutomationProfile(
+  ctx: AutomationContext,
+  id: string
+): Promise<SessionAutomationChange> {
+  const { sessions } = await loadArchive(ctx);
+  const profile = findProfile(sessions, id);
+  const identity = await hookIdentity(ctx, id);
+  // Runs start under the marker lock after rechecking the profile, so doing
+  // the whole removal under that lock means a run either started first (and
+  // removal refuses, keeping it visible) or never starts.
+  const remove = async (
+    state: AutomationState | null
+  ): Promise<{ entriesRemoved: number; pendingCleared: boolean }> => {
+    const run = state ? ownProfile(state, id) : undefined;
+    if (isRunLive(run?.running ?? null, nowOf(ctx))) {
+      throw new SessionsError(
+        "SESSIONS_BUSY",
+        `Automation profile "${id}" is running. Pause it with disable (nothing new starts), then remove it once status shows the run finished.`
+      );
+    }
+    // Fails closed: an unreadable settings file keeps the profile, so the
+    // owned entry never outlives the profile that can remove it.
+    const entriesRemoved = profile.hook
+      ? (await removeClaudeHook(profile.hook.settings, identity)).removed
+      : 0;
+    await editProfile(ctx, id, () => null);
+    if (state) delete state.profiles[id];
+    return { entriesRemoved, pendingCleared: run ? isPending(run) : false };
+  };
+  // With the archive gone no run can start (runs need its state directory),
+  // so only then is the lock-free path safe.
+  const archivePresent = await ensureStateDir(sessions.archiveRoot).then(
+    () => true,
+    () => false
+  );
+  const removed = archivePresent
+    ? await mutateAutomationState(sessions.archiveRoot, remove)
+    : await remove(null);
+  return {
+    schemaVersion: "1",
+    profileId: id,
+    hook: profile.hook
+      ? { enabled: false, entriesRemoved: removed.entriesRemoved }
+      : null,
+    schedule: profile.schedule ? { enabled: false } : null,
+    pendingCleared: removed.pendingCleared,
+    running: null,
+    removed: true,
+    warnings: [],
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Hook admission (foreground, tiny)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type HookAdmission =
+  | {
+      outcome: "accepted";
+      profileId: string;
+      daemon: "running" | "not_running" | "stale";
+    }
+  | { outcome: "skipped"; profileId: string; reason: string };
+
+/**
+ * Durably mark a profile pending for one host hook event. No parsing, no
+ * import, no network: it validates the event, rechecks the owner config under
+ * the marker lock, and returns once the marker is on disk. Errors mean the
+ * event was not accepted.
+ */
+export async function admitHookTrigger(
+  ctx: AutomationContext,
+  input: {
+    harness: SessionHookHarness;
+    profileId: string;
+    payload: unknown;
+    lockWaitMs?: number;
+    writeState?: StateWriter;
+  }
+): Promise<HookAdmission> {
+  const payload = input.payload;
+  if (
+    payload !== null &&
+    (typeof payload !== "object" ||
+      Array.isArray(payload) ||
+      ("hook_event_name" in payload &&
+        (payload as { hook_event_name: unknown }).hook_event_name !==
+          "SessionEnd"))
+  ) {
+    return {
+      outcome: "skipped",
+      profileId: input.profileId,
+      reason: "unexpected_event",
+    };
+  }
+  const { sessions } = await loadArchive(ctx);
+  const configured = sessions.automation?.find(
+    (item) => item.id === input.profileId
+  );
+  if (!configured) {
+    return {
+      outcome: "skipped",
+      profileId: input.profileId,
+      reason: "unknown_profile",
+    };
+  }
+  const enabled = configured.hook;
+  if (!enabled?.enabled || enabled.harness !== input.harness) {
+    // Nothing to admit: the state file is not touched.
+    return {
+      outcome: "skipped",
+      profileId: input.profileId,
+      reason: "hook_disabled",
+    };
+  }
+  return mutateAutomationState(
+    sessions.archiveRoot,
+    async (state): Promise<HookAdmission> => {
+      // Reread under the lock so a concurrent disable is always honoured.
+      const fresh = await loadArchive(ctx);
+      const profile = fresh.sessions.automation?.find(
+        (item) => item.id === input.profileId
+      );
+      if (!profile) {
+        return {
+          outcome: "skipped",
+          profileId: input.profileId,
+          reason: "unknown_profile",
+        };
+      }
+      if (!profile.hook?.enabled || profile.hook.harness !== input.harness) {
+        return {
+          outcome: "skipped",
+          profileId: input.profileId,
+          reason: "hook_disabled",
+        };
+      }
+      const now = nowOf(ctx);
+      admit(
+        profileState(state, profile.id),
+        "hook",
+        now,
+        profileRetries(profile)
+      );
+      return {
+        outcome: "accepted",
+        profileId: profile.id,
+        daemon: daemonState(state.daemon, now),
+      };
+    },
+    {
+      lockWaitMs: input.lockWaitMs ?? HOOK_ADMISSION_DEADLINE_MS,
+      writeState: input.writeState,
+    }
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Runs (daemon drain and explicit run-now)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface AutomationRunDeps extends AutomationContext {
+  store: SqliteAdapter;
+  syncService?: SessionsServiceDeps["syncService"];
+  pid?: number;
+  alive?: (pid: number) => boolean;
+  /** Daemon drains take the shared write lease around the imports. */
+  acquireLease?: () => Promise<
+    { ok: true; release: () => Promise<void> } | { ok: false }
+  >;
+  /**
+   * Servers (`serve`, the daemon's HTTP/MCP listener, stdio MCP) import in a
+   * child process so a long import never blocks their event loop; the CLI
+   * and SDK import in their own process.
+   */
+  inChildProcess?: boolean;
+}
+
+function summarizeRun(
+  receipts: SessionImportReceipt[],
+  triggers: SessionTriggerKind[],
+  startedAt: Date,
+  finishedAt: Date,
+  failed: { reason: string } | null
+): SessionRunRecord {
+  const sum = (pick: (receipt: SessionImportReceipt) => number): number =>
+    receipts.reduce((total, receipt) => total + pick(receipt), 0);
+  const record: SessionRunRecord = {
+    triggers,
+    startedAt: startedAt.toISOString(),
+    finishedAt: finishedAt.toISOString(),
+    outcome: "complete",
+    reason: null,
+    threads: {
+      imported: sum((r) => r.counts.imported),
+      updated: sum((r) => r.counts.updated),
+      unchanged: sum((r) => r.counts.unchanged),
+    },
+    units: {
+      incomplete: sum((r) => r.counts.incomplete),
+      failed: sum((r) => r.counts.failed + r.counts.unsupported),
+      deferred: sum((r) => r.deferredUnits),
+    },
+  };
+  if (failed) return { ...record, outcome: "failed", reason: failed.reason };
+  if (receipts.some((receipt) => receipt.status === "failed")) {
+    return { ...record, outcome: "failed", reason: "import_failed" };
+  }
+  if (receipts.some((receipt) => receipt.status === "partial")) {
+    let reason = "unit_failures";
+    if (receipts.some((receipt) => receipt.lexical.status === "failed")) {
+      reason = "index_sync_failed";
+    } else if (record.units.deferred > 0) reason = "deferred";
+    else if (record.units.incomplete > 0) reason = "incomplete_units";
+    return { ...record, outcome: "partial", reason };
+  }
+  if (receipts.every((receipt) => receipt.status === "nothing_to_do")) {
+    return { ...record, outcome: "up_to_date" };
+  }
+  return record;
+}
+
+type Begun =
+  | {
+      started: StartedRun;
+      profile: SessionAutomationProfile;
+      config: Config;
+    }
+  | { started: null; reason: string; pending: boolean };
+
+/**
+ * Run one profile through the manual importer. `trigger: "manual"` admits an
+ * explicit run request first; `null` drains work already pending. Returns
+ * `ran: false` when nothing may start (busy, backoff, trigger switched off).
+ */
+export async function runAutomationProfile(
+  deps: AutomationRunDeps,
+  profileId: string,
+  options: { trigger: "manual" | null }
+): Promise<SessionAutomationRunResult> {
+  const alive = deps.alive ?? isProcessAlive;
+  const pid = deps.pid ?? process.pid;
+  const { sessions } = await loadArchive(deps);
+  findProfile(sessions, profileId);
+  await ensureStateDir(sessions.archiveRoot);
+
+  const begun = await mutateAutomationState(
+    sessions.archiveRoot,
+    async (state): Promise<Begun> => {
+      // Authority is rechecked from the owner config under the marker lock.
+      const fresh = await loadArchive(deps);
+      const profile = fresh.sessions.automation?.find(
+        (item) => item.id === profileId
+      );
+      if (!profile) {
+        return { started: null, reason: "profile_removed", pending: false };
+      }
+      const now = nowOf(deps);
+      const run = profileState(state, profileId);
+      recoverInterrupted(run, now, alive);
+      if (options.trigger) {
+        admit(run, options.trigger, now, profileRetries(profile));
+      }
+      const allowed = run.pendingTriggers.filter(
+        (kind) =>
+          kind === "manual" ||
+          (kind === "hook" && profile.hook?.enabled === true) ||
+          (kind === "schedule" && scheduleRunnable(profile))
+      );
+      if (isPending(run) && allowed.length === 0) {
+        clearPending(run);
+        return { started: null, reason: "trigger_disabled", pending: false };
+      }
+      run.pendingTriggers = allowed;
+      const retries = profileRetries(profile);
+      if (!canStart(run, retries, now, alive)) {
+        let reason = "nothing_pending";
+        if (isRunLive(run.running, now, alive)) reason = "busy";
+        else if (isPending(run)) {
+          reason = run.attempts > retries ? "retries_exhausted" : "backoff";
+        }
+        return { started: null, reason, pending: isPending(run) };
+      }
+      return {
+        started: beginRun(run, now, pid),
+        profile,
+        config: fresh.config,
+      };
+    }
+  );
+  if (begun.started === null) {
+    return {
+      schemaVersion: "1",
+      profileId,
+      ran: false,
+      outcome: "not_started",
+      reason: begun.reason,
+      pending: begun.pending,
+      receipts: [],
+    };
+  }
+
+  const { profile, config, started } = begun;
+  const startedAt = nowOf(deps);
+  const receipts: SessionImportReceipt[] = [];
+  let failure: { failure: RunFailureClass; reason: string } | null = null;
+  const lease = deps.acquireLease ? await deps.acquireLease() : null;
+  if (lease && !lease.ok) {
+    failure = { failure: "contention", reason: "busy" };
+  } else {
+    try {
+      // Another import (a CLI import or a server's import child) holds the
+      // archive and writes the index in long transactions: report busy
+      // before touching the index rather than waiting behind it.
+      const probe = await acquireWriteLock(
+        importLockPath(sessions.archiveRoot),
+        0
+      );
+      if (!probe) {
+        throw new SessionsError(
+          "SESSIONS_BUSY",
+          "Another session import is running for this archive."
+        );
+      }
+      await probe.release();
+      // Project the current archive collections (added, changed or removed)
+      // into the index before importing.
+      const synced = await deps.store.syncCollections(config.collections);
+      if (!synced.ok) {
+        throw isIndexLockContention(synced.error)
+          ? new SessionsError("SESSIONS_BUSY", "The archive index is busy.")
+          : new SessionsError(
+              "SESSIONS_RUNTIME_FAILURE",
+              "Archive collections could not be synced into the index."
+            );
+      }
+      const service = new SessionsService({
+        config,
+        configPath: deps.configPath,
+        indexName: deps.indexName,
+        store: deps.store,
+        syncService: deps.syncService,
+        now: deps.now,
+      });
+      const importSource = (sourceId: string) =>
+        deps.inChildProcess
+          ? importInChildProcess({
+              config,
+              configPath: deps.configPath,
+              indexName: deps.indexName,
+              sourceId,
+              dryRun: false,
+              limit: profileLimit(profile),
+            })
+          : service.import(
+              { sourceId, limit: profileLimit(profile) },
+              { allowPaths: false }
+            );
+      for (const sourceId of profile.sources) {
+        if (
+          !config.sessions?.sources.some((source) => source.id === sourceId)
+        ) {
+          throw new SessionsError(
+            "SESSIONS_UNKNOWN_SOURCE",
+            "A profile source is no longer registered."
+          );
+        }
+        receipts.push(await importSource(sourceId));
+      }
+    } catch (error) {
+      failure = classifyRunError(
+        error instanceof SessionsError
+          ? error.code
+          : isIndexLockContention(error)
+            ? "SESSIONS_BUSY"
+            : null
+      );
+    } finally {
+      if (lease?.ok) await lease.release().catch(() => undefined);
+    }
+  }
+  const record = summarizeRun(
+    receipts,
+    started.triggers,
+    startedAt,
+    nowOf(deps),
+    failure
+  );
+  const failureClass: RunFailureClass | undefined =
+    record.outcome === "failed" ? (failure?.failure ?? "permanent") : undefined;
+  const pending = await mutateAutomationState(sessions.archiveRoot, (state) => {
+    const run = ownProfile(state, profileId);
+    // Removed (or removed and recreated) mid-run: this run no longer owns
+    // the record, so it settles nothing and consumes nothing.
+    if (!run || !ownsRun(run, started)) return false;
+    finishRun(run, started, record, {
+      retries: profileRetries(profile),
+      failure: failureClass,
+      now: nowOf(deps),
+    });
+    return isPending(run);
+  });
+  return {
+    schemaVersion: "1",
+    profileId,
+    ran: true,
+    outcome: record.outcome,
+    reason: record.reason,
+    pending,
+    receipts,
+  };
+}
+
+/**
+ * One daemon tick: heartbeat, coalesced schedule admissions, recovery of
+ * interrupted runs, then a drain of every profile that may start. Archives
+ * without automation profiles are left untouched.
+ */
+/**
+ * Daemon heartbeat, written on its own timer so a long import or the
+ * daemon's initial sync never makes a live daemon look absent. Archives
+ * without automation profiles are left untouched.
+ */
+export async function heartbeatAutomation(
+  deps: AutomationContext & { pid?: number; daemonStartedAt: Date }
+): Promise<void> {
+  const { sessions } = await loadArchive(deps);
+  if (
+    (sessions.automation ?? []).length === 0 ||
+    !(await stateDirExists(sessions.archiveRoot))
+  ) {
+    return;
+  }
+  await mutateAutomationState(
+    sessions.archiveRoot,
+    (state) => {
+      state.daemon = {
+        pid: deps.pid ?? process.pid,
+        startedAt: deps.daemonStartedAt.toISOString(),
+        heartbeatAt: nowOf(deps).toISOString(),
+      };
+    },
+    { lockWaitMs: HOOK_ADMISSION_DEADLINE_MS }
+  );
+}
+
+export async function tickAutomation(
+  deps: AutomationRunDeps & { daemonStartedAt: Date }
+): Promise<SessionAutomationRunResult[]> {
+  const { sessions } = await loadArchive(deps);
+  const profiles = sessions.automation ?? [];
+  if (profiles.length === 0 || !(await stateDirExists(sessions.archiveRoot))) {
+    return [];
+  }
+  const pid = deps.pid ?? process.pid;
+  const alive = deps.alive ?? isProcessAlive;
+  const daemonStart = deps.daemonStartedAt.getTime();
+  const eligible = await mutateAutomationState(
+    sessions.archiveRoot,
+    (state) => {
+      const now = nowOf(deps);
+      state.daemon = {
+        pid,
+        startedAt: deps.daemonStartedAt.toISOString(),
+        heartbeatAt: now.toISOString(),
+      };
+      const ids: string[] = [];
+      for (const profile of profiles) {
+        const cadenceMs = scheduleRunnable(profile)
+          ? automationCadenceMs(profile.schedule?.cadence)
+          : null;
+        let run = ownProfile(state, profile.id);
+        if (cadenceMs !== null) {
+          run = profileState(state, profile.id);
+          scheduleTick(run, cadenceMs, now, profileRetries(profile));
+        } else if (run) run.nextDueAt = null;
+        if (!run) continue;
+        // A record from this daemon's own pid that predates it is a leftover
+        // of an earlier process that happened to get the same pid.
+        const ownLeftover =
+          run.running?.pid === pid &&
+          Date.parse(run.running.startedAt) < daemonStart;
+        recoverInterrupted(run, now, (value) =>
+          ownLeftover ? false : alive(value)
+        );
+        if (canStart(run, profileRetries(profile), now, alive)) {
+          ids.push(profile.id);
+        }
+      }
+      return ids;
+    }
+  );
+  const results: SessionAutomationRunResult[] = [];
+  for (const id of eligible) {
+    results.push(await runAutomationProfile(deps, id, { trigger: null }));
+  }
+  return results;
+}