nemoris 0.1.0 → 0.1.2

package/src/runtime/scheduler.js

@@ -1,656 +1,656 @@
-import path from "node:path";
-import { ConfigLoader } from "../config/loader.js";
-import { buildTaskPacket } from "./task-packet.js";
-import { MemoryStore } from "../memory/memory-store.js";
-import { OpenClawShadowBridge } from "../shadow/bridge.js";
-import { readText } from "../utils/fs.js";
-import { EmbeddingIndex } from "../memory/embedding-index.js";
-import { EmbeddingService } from "../memory/embedding-service.js";
-import { MemoryBackendManager } from "../memory/backend-manager.js";
-import { planRetrievalQueries } from "../memory/retrieval-planner.js";
-import { TaskRouter } from "./task-router.js";
-import { resolveInteractionContract } from "./interaction-contract.js";
-import { IdentityBootstrapCache } from "./bootstrap-cache.js";
-import { getCached, setCached } from "./identity-cache.js";
-import { getContextLimit, getMaxOutputTokens } from "../utils/model-context-limits.js";
-import { pruneContext, estimateTokens } from "../utils/token-budget.js";
-import { PromptBuilder } from "./prompt-builder.js";
-import { resolveModelOverride } from "./model-resolution.js";
-
-function normalizePolicy(policy) {
-  const categories = policy.categories || {};
-  return {
-    allow_durable_writes: policy.allowDurableWrites ?? false,
-    allow_identity_updates: policy.allowIdentityUpdates ?? false,
-    require_source_reference: policy.requireSourceReference ?? false,
-    require_write_reason: policy.requireWriteReason ?? false,
-    max_writes_per_run: policy.maxWritesPerRun ?? 0,
-    categories: {
-      allowed: categories.allowed || [],
-      blocked: categories.blocked || []
-    }
-  };
-}
-
-function deepMerge(base, override) {
-  if (Array.isArray(base) || Array.isArray(override)) {
-    return Array.isArray(override) ? [...override] : Array.isArray(base) ? [...base] : [];
-  }
-
-  if (!base || typeof base !== "object") {
-    return override === undefined ? base : override;
-  }
-
-  if (!override || typeof override !== "object") {
-    return override === undefined ? { ...base } : override;
-  }
-
-  const merged = { ...base };
-  for (const [key, value] of Object.entries(override)) {
-    merged[key] = key in base ? deepMerge(base[key], value) : value;
-  }
-  return merged;
-}
-
-function normalizeJob(jobId, jobConfig, runtime = {}) {
-  return {
-    id: jobId,
-    trigger: jobConfig.trigger,
-    taskType: jobConfig.taskType,
-    agentId: jobConfig.agentId,
-    modelLane: jobConfig.modelLane,
-    outputTarget: jobConfig.outputTarget,
-    idempotencyKey: jobConfig.idempotencyKey,
-    liveJobHints: jobConfig.liveJobHints || [],
-    memoryBackends: jobConfig.memoryBackends || null,
-    qmdSupplementLimit: jobConfig.qmdSupplementLimit ?? null,
-    memoryLimit: jobConfig.memoryLimit ?? null,
-    interactionContract: jobConfig.interactionContract || null,
-    reportFallback: jobConfig.reportFallback
-      ? {
-          enabled: jobConfig.reportFallback.enabled ?? false,
-          lane: jobConfig.reportFallback.lane || runtime.runtime?.reportFallback?.lane || "report_fallback_lowcost",
-          allowedFailureClasses:
-            jobConfig.reportFallback.allowedFailureClasses ||
-            runtime.runtime?.reportFallback?.allowedFailureClasses ||
-            ["timeout", "provider_loading"]
-        }
-      : null,
-    outputContract: normalizeOutputContract(jobConfig.outputContract || null, runtime.outputContracts || null),
-    reportGuidance: normalizeReportGuidance(jobConfig.reportGuidance || null),
-    budget: {
-      maxTokens: jobConfig.budget?.maxTokens ?? 4000,
-      maxRuntimeSeconds: jobConfig.budget?.maxRuntimeSeconds ?? 30
-    },
-    retry: {
-      maxAttempts: jobConfig.retry?.maxAttempts ?? 1
-    },
-    stop: {
-      haltOnPolicyError: jobConfig.stop?.haltOnPolicyError ?? true,
-      haltOnBudgetExceeded: jobConfig.stop?.haltOnBudgetExceeded ?? true
-    }
-  };
-}
-
-export class Scheduler {
-  constructor({ projectRoot, liveRoot, stateRoot }) {
-    this.projectRoot = projectRoot;
-    this.liveRoot = liveRoot;
-    this.stateRoot = stateRoot;
-    this.loader = new ConfigLoader({ rootDir: path.join(projectRoot, "config") });
-    this.memoryStore = new MemoryStore({ rootDir: path.join(stateRoot, "memory") });
-    this.bridge = new OpenClawShadowBridge({ liveRoot });
-    this.embeddingIndex = new EmbeddingIndex({
-      rootDir: path.join(stateRoot, "memory"),
-      embeddingService: new EmbeddingService({ projectRoot })
-    });
-    this.backendManager = new MemoryBackendManager({
-      memoryStore: this.memoryStore,
-      embeddingIndex: this.embeddingIndex,
-      liveRoot
-    });
-    this.identityCache = new IdentityBootstrapCache({
-      rootDir: path.join(stateRoot, "bootstrap", "identity")
-    });
-  }
-
-  async loadRuntime() {
-    const config = await this.loader.loadAll();
-    this.identityCache.ttlMs = config.runtime?.bootstrapCache?.identityTtlMs ?? this.identityCache.ttlMs;
-    return config;
-  }
-
-  async listJobPlans() {
-    const runtime = await this.loadRuntime();
-    return Object.entries(runtime.jobs).map(([jobId, jobConfig]) => {
-      const normalizedJob = normalizeJob(jobId, jobConfig, runtime);
-      const agent = runtime.agents[normalizedJob.agentId];
-      return {
-        ...normalizedJob,
-        workspaceRoot: agent?.workspaceRoot || null,
-        primaryLane: agent?.primaryLane || null,
-        deliveryProfile: agent?.delivery?.profile || null
-      };
-    });
-  }
-
-  async hydrateJob(jobId, options = {}) {
-    const runtime = await this.loadRuntime();
-    const rawJob = runtime.jobs[jobId];
-    if (!rawJob) {
-      throw new Error(`Unknown job: ${jobId}`);
-    }
-
-    const job = normalizeJob(jobId, rawJob, runtime);
-    const agent = runtime.agents[job.agentId];
-    if (!agent) {
-      throw new Error(`Unknown agent for job ${jobId}: ${job.agentId}`);
-    }
-
-    if (options.shadowImport) {
-      const policy = normalizePolicy(runtime.policies[`memory-${agent.memoryPolicy}`] || runtime.policies[agent.memoryPolicy]);
-      await this.bridge.importWorkspaceSnapshot(job.agentId, this.memoryStore, policy, {
-        workspaceOverride: agent.workspaceRoot
-      });
-    }
-
-    const objective =
-      options.objective ||
-      `Execute job ${job.id} of type ${job.taskType} with bounded runtime and low context overhead.`;
-
-    const cacheKey = [
-      agent.soulRef || "",
-      agent.purposeRef || "",
-      agent.userRef || "",
-      (agent.workspaceContextFiles || []).join(","),
-      agent.workspaceRoot || ""
-    ].join("|");
-
-    let identity = getCached(cacheKey);
-    if (!identity) {
-      identity = await this.identityCache.get(
-        job.agentId,
-        {
-          soulRef: agent.soulRef || null, purposeRef: agent.purposeRef || null, userRef: agent.userRef || null },
-        () => loadAgentIdentity(this.projectRoot, agent)
-      );
-      setCached(cacheKey, identity);
-    }
-    const effectiveMemoryBackends = job.memoryBackends || agent.memoryBackends || ["file"];
-    const effectiveQmdSupplementLimit = job.qmdSupplementLimit ?? agent.qmdSupplementLimit ?? 2;
-    const effectiveMemoryLimit = job.memoryLimit ?? options.memoryLimit ?? 8;
-    const effectiveInteractionContract = resolveInteractionContract(agent.interactionContract || null, job.interactionContract);
-    const effectiveReportGuidance = options.reportGuidanceOverride
-      ? normalizeReportGuidance(deepMerge(job.reportGuidance || {}, options.reportGuidanceOverride))
-      : job.reportGuidance;
-    const effectiveRetrievalBlend = options.retrievalBlendOverride
-      ? {
-          ...(runtime.runtime?.retrieval || {}),
-          ...options.retrievalBlendOverride
-        }
-      : runtime.runtime?.retrieval || null;
-    const retrievalQueries = planRetrievalQueries({
-      objective,
-      taskType: job.taskType,
-      purpose: identity?.purpose,
-      identity,
-      reportGuidance: effectiveReportGuidance
-    });
-
-    const packet = await buildTaskPacket({
-      agentId: job.agentId,
-      objective,
-      memoryStore: this.memoryStore,
-      backendManager: this.backendManager,
-      workspaceRoot: agent.workspaceRoot,
-      backendOrder: effectiveMemoryBackends,
-      qmdSupplementLimit: effectiveQmdSupplementLimit,
-      retrievalQueries,
-      identity,
-      interactionContract: effectiveInteractionContract,
-      outputContract: job.outputContract,
-      reportGuidance: effectiveReportGuidance,
-      allowedTools: inferToolsFromPolicy(runtime.policies[`tools-${agent.toolPolicy}`] || runtime.policies[agent.toolPolicy]),
-      artifactRefs: options.artifactRefs || [],
-      budget: job.budget,
-      memoryLimit: effectiveMemoryLimit,
-      retrievalBlend: effectiveRetrievalBlend
-    });
-
-    const allowedTools = inferToolsFromPolicy(runtime.policies[`tools-${agent.toolPolicy}`] || runtime.policies[agent.toolPolicy]);
-    const routing = new TaskRouter(runtime.taskRouter).choose({
-      jobId: job.id,
-      taskType: job.taskType,
-      objective,
-      requestedLane: job.modelLane,
-      agentPrimaryLane: agent.primaryLane,
-      outputTarget: job.outputTarget || null,
-      requiresPingback: effectiveInteractionContract.requiresPingback,
-      notifyOnDone: effectiveInteractionContract.notifyOnDone,
-      deliveryProfile: agent.delivery?.profile || null,
-      artifactRefs: options.artifactRefs || [],
-      allowedTools
-    });
-
-    return {
-      job,
-      agent: {
-        id: job.agentId,
-        name: agent.name || job.agentId,
-        workspaceRoot: agent.workspaceRoot,
-        primaryLane: agent.primaryLane,
-        fallbackLane: agent.fallbackLane || null,
-        memoryPolicy: agent.memoryPolicy,
-        toolPolicy: agent.toolPolicy,
-        soulRef: agent.soulRef || null,
-        purposeRef: agent.purposeRef || null,
-        memoryBackendOrder: effectiveMemoryBackends,
-        memoryBackendSource: job.memoryBackends ? "job" : "agent",
-        qmdSupplementLimit: effectiveQmdSupplementLimit,
-        memoryLimit: effectiveMemoryLimit,
-        interactionContractSource: job.interactionContract ? "job" : agent.interactionContract ? "agent" : "default",
-        interactionContract: effectiveInteractionContract,
-        deliveryProfile: agent.delivery?.profile || null,
-        memoryBackends: await this.backendManager.inspect(job.agentId, agent.workspaceRoot),
-        reportGuidance: effectiveReportGuidance,
-        retrievalBlend: effectiveRetrievalBlend,
-        execApprovals: agent.execApprovals ?? false,
-      },
-      packet,
-      routing: {
-        requestedLane: job.modelLane,
-        selectedLane: routing.selectedLane,
-        routeMode: routing.routeMode,
-        matchedRule: routing.matchedRule,
-        reasons: routing.reasons,
-        description: routing.description || null
-      }
-    };
-  }
-
-  /**
-   * Hydrate an interactive job (Telegram message or agent dispatch) into a
-   * plan object compatible with executor.executeHydratedJob(). Unlike
-   * hydrateJob(), this does not look up a TOML job definition — it builds
-   * the plan from the raw message text and the target agent's config.
-   */
-  async hydrateInteractiveJob({ jobId, agentId, input, imageRefs = null, sessionId = null, contextLedger = null, conversationContext = null }, options = {}) {
-    const runtime = await this.loadRuntime();
-    const agent = runtime.agents[agentId];
-    if (!agent) {
-      throw new Error(`Unknown agent for interactive job ${jobId}: ${agentId}`);
-    }
-
-    if (options.shadowImport && agent.workspaceRoot) {
-      const policy = normalizePolicy(runtime.policies[`memory-${agent.memoryPolicy}`] || runtime.policies[agent.memoryPolicy]);
-      await this.bridge.importWorkspaceSnapshot(agentId, this.memoryStore, policy, {
-        workspaceOverride: agent.workspaceRoot
-      });
-    }
-
-    const objective = input;
-
-    const cacheKey = [
-      agent.soulRef || "",
-      agent.purposeRef || "",
-      agent.userRef || "",
-      (agent.workspaceContextFiles || []).join(","),
-      agent.workspaceRoot || ""
-    ].join("|");
-
-    let identity = getCached(cacheKey);
-    if (!identity) {
-      identity = await this.identityCache.get(
-        agentId,
-        { soulRef: agent.soulRef || null, purposeRef: agent.purposeRef || null, userRef: agent.userRef || null },
-        () => loadAgentIdentity(this.projectRoot, agent)
-      );
-      setCached(cacheKey, identity);
-    }
-
-    const effectiveMemoryBackends = agent.memoryBackends || ["file"];
-    const effectiveMemoryLimit = options.memoryLimit ?? 8;
-    // Interactive jobs use a conversational contract — strip completion_sections
-    // and handoff_format that force structured JSON output
-    const effectiveInteractionContract = {
-      ...resolveInteractionContract(agent.interactionContract || null, null),
-      completionSections: [],
-      handoffFormat: "conversational",
-      ackMode: "silent",
-      requiresPingback: false,
-      notifyOnDone: false,
-    };
-    const retrievalQueries = planRetrievalQueries({
-      objective,
-      taskType: "interactive",
-      purpose: identity?.purpose,
-      identity,
-    });
-
-    const modelOverride = resolveModelOverride(options.modelOverride, { routerConfig: runtime.router });
-
-    const modelId = modelOverride || runtime.router[agent.primaryLane]?.primary || "default";
-    const maxOutput = getMaxOutputTokens(modelId);
-    const contextLimit = getContextLimit(modelId);
-
-    let effectiveContext;
-    let tokenBudgetMeta = { removed: 0, estimatedTokens: 0 };
-
-    // Try Context Ledger path (Phase 3)
-    if (contextLedger && sessionId) {
-      try {
-        const { snapshot, events } = contextLedger.loadState(sessionId);
-        if (events.length > 0) {
-          const builder = new PromptBuilder({ contextLedger });
-          let systemText = `You are ${identity?.soul || agentId}. ${identity?.purpose || ""}\n\n${(identity?.contextFiles || []).map(f => `[File: ${f.name}]\n${f.content}`).join("\n\n")}`;
-          if (options && options.focusMode && options.focusMode !== "off") {
-            const focusModeInstructions = {
-              deep: "Current mode: deep work. Be terse. No preamble. No summaries. Direct answers only.",
-              planning: "Current mode: planning. Use structured bullet points and numbered lists. Surface tradeoffs."
-            };
-            const focusInstruction = focusModeInstructions[options.focusMode] || `Current mode: ${options.focusMode}.`;
-            systemText += `\n\n${focusInstruction}`;
-          }
-          if (options && options.sourceType === 'agent') {
-            const agentLabel = options.sourceAgentId || 'unknown';
-            systemText += `\n\nContext: This message is from a peer agent (${agentLabel}), not from the human operator. Reply in structured, direct format. No conversational padding. Route your reply back to the agent.`;
-          }
-          const tools = inferToolsFromPolicy(runtime.policies[`tools-${agent.toolPolicy}`] || runtime.policies[agent.toolPolicy]);
-          
-          const result = await builder.buildPrompt({
-            sessionId,
-            events,
-            snapshot,
-            systemText,
-            tools: (tools || []).map(t => ({ name: t })),
-            tokenBudgetTotal: contextLimit
-          });
-
-          effectiveContext = result.messages;
-          tokenBudgetMeta = { removed: 0, estimatedTokens: result.tokenEstimate };
-          
-          console.log(JSON.stringify({
-            service: "prompt_builder",
-            session_id: sessionId,
-            prefix_hash: result.prefixHash,
-            token_estimate: result.tokenEstimate
-          }));
-        }
-      } catch (err) {
-        console.error(JSON.stringify({ service: "prompt_builder", event: "error", error: err.message, session_id: sessionId }));
-      }
-    }
-
-    // Fallback to blob-based path
-    if (!effectiveContext && conversationContext) {
-      const parsed = JSON.parse(conversationContext);
-      const { pruned, removed, estimatedTokens } = pruneContext(parsed, contextLimit);
-      effectiveContext = pruned;
-      tokenBudgetMeta = { removed, estimatedTokens };
-    }
-
-    // Inject focus mode into identity soul for blob path
-    if (options && options.focusMode && options.focusMode !== "off") {
-      const focusModeInstructions = {
-        deep: "Current mode: deep work. Be terse. No preamble. No summaries. Direct answers only.",
-        planning: "Current mode: planning. Use structured bullet points and numbered lists. Surface tradeoffs."
-      };
-      const focusInstruction = focusModeInstructions[options.focusMode] || `Current mode: ${options.focusMode}.`;
-      identity = { ...identity, soul: (identity?.soul || "") + `\n\n${focusInstruction}` };
-    }
-
-    // Inject source context for agent-originated messages
-    if (options && options.sourceType === 'agent') {
-      const agentLabel = options.sourceAgentId || 'unknown';
-      const agentInstruction = `\n\nContext: This message is from a peer agent (${agentLabel}), not from the human operator. Reply in structured, direct format. No conversational padding. Route your reply back to the agent.`;
-      identity = { ...identity, soul: (identity?.soul || "") + agentInstruction };
-    }
-
-    console.log(JSON.stringify({
-      service: "token_budget",
-      model: modelId,
-      estimated_tokens: tokenBudgetMeta.estimatedTokens,
-      removed_turns: tokenBudgetMeta.removed,
-      max_output: maxOutput,
-    }));
-
-    const packet = await buildTaskPacket({
-      agentId,
-      objective,
-      memoryStore: this.memoryStore,
-      backendManager: this.backendManager,
-      workspaceRoot: agent.workspaceRoot,
-      backendOrder: effectiveMemoryBackends,
-      qmdSupplementLimit: agent.qmdSupplementLimit ?? 2,
-      retrievalQueries,
-      identity,
-      interactionContract: effectiveInteractionContract,
-      outputContract: null,
-      reportGuidance: null,
-      allowedTools: inferToolsFromPolicy(runtime.policies[`tools-${agent.toolPolicy}`] || runtime.policies[agent.toolPolicy]),
-      artifactRefs: [],
-      budget: { maxTokens: maxOutput, maxRuntimeSeconds: 120 },
-      memoryLimit: effectiveMemoryLimit,
-      retrievalBlend: runtime.runtime?.retrieval || null,
-      conversationContext: effectiveContext,
-    });
-    packet.modelOverride = modelOverride;
-    packet.imageRefs = imageRefs;
-    if (options.thinkMode) {
-      packet.thinkMode = options.thinkMode;
-    }
-
-    const allowedTools = inferToolsFromPolicy(runtime.policies[`tools-${agent.toolPolicy}`] || runtime.policies[agent.toolPolicy]);
-    const router = new TaskRouter(runtime.taskRouter);
-    const routing = router.choose({
-      jobId,
-      taskType: "interactive",
-      objective,
-      requestedLane: null,
-      agentPrimaryLane: agent.primaryLane,
-      outputTarget: null,
-      requiresPingback: effectiveInteractionContract.requiresPingback,
-      notifyOnDone: effectiveInteractionContract.notifyOnDone,
-      deliveryProfile: agent.delivery?.profile || null,
-      artifactRefs: [],
-      allowedTools
-    });
-
-    return {
-      job: {
-        id: jobId,
-        trigger: "interactive",
-        taskType: "interactive",
-        agentId,
-        modelLane: null,
-        outputTarget: null,
-        idempotencyKey: null,
-        liveJobHints: [],
-        budget: { maxTokens: maxOutput, maxRuntimeSeconds: 120 },
-      },
-      agent: {
-        id: agentId,
-        name: agent.name || agentId,
-        workspaceRoot: agent.workspaceRoot,
-        primaryLane: agent.primaryLane,
-        fallbackLane: agent.fallbackLane || null,
-        memoryPolicy: agent.memoryPolicy,
-        toolPolicy: agent.toolPolicy,
-        soulRef: agent.soulRef || null,
-        purposeRef: agent.purposeRef || null,
-        memoryBackendOrder: effectiveMemoryBackends,
-        memoryBackendSource: "agent",
-        qmdSupplementLimit: agent.qmdSupplementLimit ?? 2,
-        memoryLimit: effectiveMemoryLimit,
-        interactionContractSource: agent.interactionContract ? "agent" : "default",
-        interactionContract: effectiveInteractionContract,
-        deliveryProfile: agent.delivery?.profile || null,
-        memoryBackends: await this.backendManager.inspect(agentId, agent.workspaceRoot),
-        reportGuidance: null,
-        retrievalBlend: runtime.runtime?.retrieval || null,
-        execApprovals: agent.execApprovals ?? false,
-      },
-      packet,
-      routing: {
-        requestedLane: null,
-        selectedLane: routing.selectedLane,
-        routeMode: routing.routeMode,
-        matchedRule: routing.matchedRule,
-        reasons: routing.reasons,
-        description: routing.description || null
-      }
-    };
-  }
-
-  async summarizeLiveCron() {
-    const jobs = await this.bridge.loadCronJobs();
-    return jobs.map((job) => ({
-      id: job.id,
-      name: job.name,
-      description: job.description || null,
-      enabled: job.enabled,
-      schedule: job.schedule,
-      targetModel: job.payload?.model || null,
-      timeoutSeconds: job.payload?.timeoutSeconds || null,
-      kind: job.payload?.kind || null,
-      messagePreview: String(job.payload?.message || job.payload?.text || "").slice(0, 160),
-      lastStatus: job.state?.lastStatus || null,
-      consecutiveErrors: job.state?.consecutiveErrors || 0
-    }));
-  }
-
-  async compareJobs() {
-    const [v2Jobs, liveJobs] = await Promise.all([this.listJobPlans(), this.summarizeLiveCron()]);
-
-    return v2Jobs.map((job) => ({
-      v2JobId: job.id,
-      v2TaskType: job.taskType,
-      v2Trigger: job.trigger,
-      liveJobHints: job.liveJobHints,
-      closestLiveJobs: liveJobs
-        .map((liveJob) => ({
-          ...liveJob,
-          _score: compareJobText(job, liveJob)
-        }))
-        .filter((liveJob) => liveJob._score > 0)
-        .sort((a, b) => b._score - a._score)
-        .slice(0, 3)
-        .map(({ _score, ...liveJob }) => liveJob)
-    }));
-  }
-}
-
-function normalizeOutputContract(contract, outputContracts = null) {
-  const defaultProfile = outputContracts?.profiles?.default || null;
-  if (!contract) {
-    if (!defaultProfile) return null;
-    return {
-      format: null,
-      requiredSections: [],
-      styleHints: [],
-      profile: {
-        requireStatus: defaultProfile.requireStatus ?? false,
-        sectionStyle: defaultProfile.sectionStyle || "bullets",
-        requireSectionItems: defaultProfile.requireSectionItems ?? true,
-        templateLines: defaultProfile.templateLines || []
-      }
-    };
-  }
-  const profileKey = String(contract.format || "").replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
-  const profile = outputContracts?.profiles?.[profileKey] || defaultProfile || null;
-  return {
-    format: contract.format || null,
-    requiredSections: contract.requiredSections || [],
-    styleHints: contract.styleHints || [],
-    profile: profile
-      ? {
-          requireStatus: profile.requireStatus ?? false,
-          sectionStyle: profile.sectionStyle || "bullets",
-          requireSectionItems: profile.requireSectionItems ?? true,
-          templateLines: profile.templateLines || []
-        }
-      : null
-  };
-}
-
-function normalizeReportGuidance(reportGuidance) {
-  if (!reportGuidance) return null;
-  return {
-    focus: reportGuidance.focus || [],
-    qualityChecks: reportGuidance.qualityChecks || [],
-    avoid: reportGuidance.avoid || []
-  };
-}
-
-async function loadAgentIdentity(projectRoot, agent) {
-  const cacheKey = [
-    agent.soulRef || "",
-    agent.purposeRef || "",
-    agent.userRef || "",
-    (agent.workspaceContextFiles || []).join(","),
-    agent.workspaceRoot || ""
-  ].join("|");
-
-  const cached = getCached(cacheKey);
-  if (cached) {
-    console.log(`[identity-cache] hit for agent ${agent.id || "unknown"}`);
-    return cached;
-  }
-
-  console.log(`[identity-cache] miss — loading from disk for agent ${agent.id || "unknown"}`);
-
-  const soul = await readOptionalIdentity(projectRoot, agent.soulRef);
-  const purpose = await readOptionalIdentity(projectRoot, agent.purposeRef);
-  const user = await readOptionalIdentity(projectRoot, agent.userRef);
-
-  // Load workspace context files (MEMORY.md, AGENTS.md, etc.) relative to workspace_root
-  const contextFiles = [];
-  if (agent.workspaceRoot && agent.workspaceContextFiles?.length) {
-    const cap = agent.workspaceContextCap ?? 8000;
-    for (const filename of agent.workspaceContextFiles) {
-      const filePath = path.join(agent.workspaceRoot, filename);
-      const content = await readText(filePath, null);
-      if (content) {
-        const capped = content.length > cap ? content.slice(0, cap) + `\n\n[truncated — full file at ${filePath}]` : content;
-        contextFiles.push({ name: filename, content: capped });
-      }
-    }
-  }
-
-  const result = (!soul && !purpose && !user && contextFiles.length === 0)
-    ? null
-    : {
-        soul,
-        purpose,
-        user,
-        contextFiles
-      };
-
-  setCached(cacheKey, result);
-  return result;
-}
-
-async function readOptionalIdentity(projectRoot, ref) {
-  if (!ref) return null;
-  return readText(path.isAbsolute(ref) ? ref : path.join(projectRoot, ref), null);
-}
-
-function inferToolsFromPolicy(policy) {
-  return policy?.allowed || [];
-}
-
-function compareJobText(v2Job, liveJob) {
-  const haystack = `${liveJob.name || ""} ${liveJob.description || ""} ${liveJob.id || ""} ${liveJob.kind || ""} ${liveJob.messagePreview || ""}`.toLowerCase();
-  const stopwords = new Set(["check", "job", "task", "run", "daily", "hourly", "every", "rollup", "health"]);
-  const needles = [...v2Job.taskType.split("_"), ...v2Job.id.split("-")].filter(
-    (token) => token.length > 2 && !stopwords.has(token.toLowerCase())
-  );
-  let score = 0;
-  for (const token of needles) {
-    if (haystack.includes(token.toLowerCase())) score += 1;
-  }
-  for (const hint of v2Job.liveJobHints || []) {
-    if (haystack.includes(String(hint).toLowerCase())) score += 3;
-  }
-  return score;
-}
+import path from "node:path";
+import { ConfigLoader } from "../config/loader.js";
+import { buildTaskPacket } from "./task-packet.js";
+import { MemoryStore } from "../memory/memory-store.js";
+import { OpenClawShadowBridge } from "../shadow/bridge.js";
+import { readText } from "../utils/fs.js";
+import { EmbeddingIndex } from "../memory/embedding-index.js";
+import { EmbeddingService } from "../memory/embedding-service.js";
+import { MemoryBackendManager } from "../memory/backend-manager.js";
+import { planRetrievalQueries } from "../memory/retrieval-planner.js";
+import { TaskRouter } from "./task-router.js";
+import { resolveInteractionContract } from "./interaction-contract.js";
+import { IdentityBootstrapCache } from "./bootstrap-cache.js";
+import { getCached, setCached } from "./identity-cache.js";
+import { getContextLimit, getMaxOutputTokens } from "../utils/model-context-limits.js";
+import { pruneContext, estimateTokens } from "../utils/token-budget.js";
+import { PromptBuilder } from "./prompt-builder.js";
+import { resolveModelOverride } from "./model-resolution.js";
+
+function normalizePolicy(policy) {
+  const categories = policy.categories || {};
+  return {
+    allow_durable_writes: policy.allowDurableWrites ?? false,
+    allow_identity_updates: policy.allowIdentityUpdates ?? false,
+    require_source_reference: policy.requireSourceReference ?? false,
+    require_write_reason: policy.requireWriteReason ?? false,
+    max_writes_per_run: policy.maxWritesPerRun ?? 0,
+    categories: {
+      allowed: categories.allowed || [],
+      blocked: categories.blocked || []
+    }
+  };
+}
+
+function deepMerge(base, override) {
+  if (Array.isArray(base) || Array.isArray(override)) {
+    return Array.isArray(override) ? [...override] : Array.isArray(base) ? [...base] : [];
+  }
+
+  if (!base || typeof base !== "object") {
+    return override === undefined ? base : override;
+  }
+
+  if (!override || typeof override !== "object") {
+    return override === undefined ? { ...base } : override;
+  }
+
+  const merged = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    merged[key] = key in base ? deepMerge(base[key], value) : value;
+  }
+  return merged;
+}
+
+function normalizeJob(jobId, jobConfig, runtime = {}) {
+  return {
+    id: jobId,
+    trigger: jobConfig.trigger,
+    taskType: jobConfig.taskType,
+    agentId: jobConfig.agentId,
+    modelLane: jobConfig.modelLane,
+    outputTarget: jobConfig.outputTarget,
+    idempotencyKey: jobConfig.idempotencyKey,
+    liveJobHints: jobConfig.liveJobHints || [],
+    memoryBackends: jobConfig.memoryBackends || null,
+    qmdSupplementLimit: jobConfig.qmdSupplementLimit ?? null,
+    memoryLimit: jobConfig.memoryLimit ?? null,
+    interactionContract: jobConfig.interactionContract || null,
+    reportFallback: jobConfig.reportFallback
+      ? {
+          enabled: jobConfig.reportFallback.enabled ?? false,
+          lane: jobConfig.reportFallback.lane || runtime.runtime?.reportFallback?.lane || "report_fallback_lowcost",
+          allowedFailureClasses:
+            jobConfig.reportFallback.allowedFailureClasses ||
+            runtime.runtime?.reportFallback?.allowedFailureClasses ||
+            ["timeout", "provider_loading"]
+        }
+      : null,
+    outputContract: normalizeOutputContract(jobConfig.outputContract || null, runtime.outputContracts || null),
+    reportGuidance: normalizeReportGuidance(jobConfig.reportGuidance || null),
+    budget: {
+      maxTokens: jobConfig.budget?.maxTokens ?? 4000,
+      maxRuntimeSeconds: jobConfig.budget?.maxRuntimeSeconds ?? 30
+    },
+    retry: {
+      maxAttempts: jobConfig.retry?.maxAttempts ?? 1
+    },
+    stop: {
+      haltOnPolicyError: jobConfig.stop?.haltOnPolicyError ?? true,
+      haltOnBudgetExceeded: jobConfig.stop?.haltOnBudgetExceeded ?? true
+    }
+  };
+}
+
+export class Scheduler {
+  constructor({ projectRoot, liveRoot, stateRoot }) {
+    this.projectRoot = projectRoot;
+    this.liveRoot = liveRoot;
+    this.stateRoot = stateRoot;
+    this.loader = new ConfigLoader({ rootDir: path.join(projectRoot, "config") });
+    this.memoryStore = new MemoryStore({ rootDir: path.join(stateRoot, "memory") });
+    this.bridge = new OpenClawShadowBridge({ liveRoot });
+    this.embeddingIndex = new EmbeddingIndex({
+      rootDir: path.join(stateRoot, "memory"),
+      embeddingService: new EmbeddingService({ projectRoot })
+    });
+    this.backendManager = new MemoryBackendManager({
+      memoryStore: this.memoryStore,
+      embeddingIndex: this.embeddingIndex,
+      liveRoot
+    });
+    this.identityCache = new IdentityBootstrapCache({
+      rootDir: path.join(stateRoot, "bootstrap", "identity")
+    });
+  }
+
+  async loadRuntime() {
+    const config = await this.loader.loadAll();
+    this.identityCache.ttlMs = config.runtime?.bootstrapCache?.identityTtlMs ?? this.identityCache.ttlMs;
+    return config;
+  }
+
+  async listJobPlans() {
+    const runtime = await this.loadRuntime();
+    return Object.entries(runtime.jobs).map(([jobId, jobConfig]) => {
+      const normalizedJob = normalizeJob(jobId, jobConfig, runtime);
+      const agent = runtime.agents[normalizedJob.agentId];
+      return {
+        ...normalizedJob,
+        workspaceRoot: agent?.workspaceRoot || null,
+        primaryLane: agent?.primaryLane || null,
+        deliveryProfile: agent?.delivery?.profile || null
+      };
+    });
+  }
+
+  async hydrateJob(jobId, options = {}) {
+    const runtime = await this.loadRuntime();
+    const rawJob = runtime.jobs[jobId];
+    if (!rawJob) {
+      throw new Error(`Unknown job: ${jobId}`);
+    }
+
+    const job = normalizeJob(jobId, rawJob, runtime);
+    const agent = runtime.agents[job.agentId];
+    if (!agent) {
+      throw new Error(`Unknown agent for job ${jobId}: ${job.agentId}`);
+    }
+
+    if (options.shadowImport) {
+      const policy = normalizePolicy(runtime.policies[`memory-${agent.memoryPolicy}`] || runtime.policies[agent.memoryPolicy]);
+      await this.bridge.importWorkspaceSnapshot(job.agentId, this.memoryStore, policy, {
+        workspaceOverride: agent.workspaceRoot
+      });
+    }
+
+    const objective =
+      options.objective ||
+      `Execute job ${job.id} of type ${job.taskType} with bounded runtime and low context overhead.`;
+
+    const cacheKey = [
+      agent.soulRef || "",
+      agent.purposeRef || "",
+      agent.userRef || "",
+      (agent.workspaceContextFiles || []).join(","),
+      agent.workspaceRoot || ""
+    ].join("|");
+
+    let identity = getCached(cacheKey);
+    if (!identity) {
+      identity = await this.identityCache.get(
+        job.agentId,
+        {
+          soulRef: agent.soulRef || null, purposeRef: agent.purposeRef || null, userRef: agent.userRef || null },
+        () => loadAgentIdentity(this.projectRoot, agent)
+      );
+      setCached(cacheKey, identity);
+    }
+    const effectiveMemoryBackends = job.memoryBackends || agent.memoryBackends || ["file"];
+    const effectiveQmdSupplementLimit = job.qmdSupplementLimit ?? agent.qmdSupplementLimit ?? 2;
+    const effectiveMemoryLimit = job.memoryLimit ?? options.memoryLimit ?? 8;
+    const effectiveInteractionContract = resolveInteractionContract(agent.interactionContract || null, job.interactionContract);
+    const effectiveReportGuidance = options.reportGuidanceOverride
+      ? normalizeReportGuidance(deepMerge(job.reportGuidance || {}, options.reportGuidanceOverride))
+      : job.reportGuidance;
+    const effectiveRetrievalBlend = options.retrievalBlendOverride
+      ? {
+          ...(runtime.runtime?.retrieval || {}),
+          ...options.retrievalBlendOverride
+        }
+      : runtime.runtime?.retrieval || null;
+    const retrievalQueries = planRetrievalQueries({
+      objective,
+      taskType: job.taskType,
+      purpose: identity?.purpose,
+      identity,
+      reportGuidance: effectiveReportGuidance
+    });
+
+    const packet = await buildTaskPacket({
+      agentId: job.agentId,
+      objective,
+      memoryStore: this.memoryStore,
+      backendManager: this.backendManager,
+      workspaceRoot: agent.workspaceRoot,
+      backendOrder: effectiveMemoryBackends,
+      qmdSupplementLimit: effectiveQmdSupplementLimit,
+      retrievalQueries,
+      identity,
+      interactionContract: effectiveInteractionContract,
+      outputContract: job.outputContract,
+      reportGuidance: effectiveReportGuidance,
+      allowedTools: inferToolsFromPolicy(runtime.policies[`tools-${agent.toolPolicy}`] || runtime.policies[agent.toolPolicy]),
+      artifactRefs: options.artifactRefs || [],
+      budget: job.budget,
+      memoryLimit: effectiveMemoryLimit,
+      retrievalBlend: effectiveRetrievalBlend
+    });
+
+    const allowedTools = inferToolsFromPolicy(runtime.policies[`tools-${agent.toolPolicy}`] || runtime.policies[agent.toolPolicy]);
+    const routing = new TaskRouter(runtime.taskRouter).choose({
+      jobId: job.id,
+      taskType: job.taskType,
+      objective,
+      requestedLane: job.modelLane,
+      agentPrimaryLane: agent.primaryLane,
+      outputTarget: job.outputTarget || null,
+      requiresPingback: effectiveInteractionContract.requiresPingback,
+      notifyOnDone: effectiveInteractionContract.notifyOnDone,
+      deliveryProfile: agent.delivery?.profile || null,
+      artifactRefs: options.artifactRefs || [],
+      allowedTools
+    });
+
+    return {
+      job,
+      agent: {
+        id: job.agentId,
+        name: agent.name || job.agentId,
+        workspaceRoot: agent.workspaceRoot,
+        primaryLane: agent.primaryLane,
+        fallbackLane: agent.fallbackLane || null,
+        memoryPolicy: agent.memoryPolicy,
+        toolPolicy: agent.toolPolicy,
+        soulRef: agent.soulRef || null,
+        purposeRef: agent.purposeRef || null,
+        memoryBackendOrder: effectiveMemoryBackends,
+        memoryBackendSource: job.memoryBackends ? "job" : "agent",
+        qmdSupplementLimit: effectiveQmdSupplementLimit,
+        memoryLimit: effectiveMemoryLimit,
+        interactionContractSource: job.interactionContract ? "job" : agent.interactionContract ? "agent" : "default",
+        interactionContract: effectiveInteractionContract,
+        deliveryProfile: agent.delivery?.profile || null,
+        memoryBackends: await this.backendManager.inspect(job.agentId, agent.workspaceRoot),
+        reportGuidance: effectiveReportGuidance,
+        retrievalBlend: effectiveRetrievalBlend,
+        execApprovals: agent.execApprovals ?? false,
+      },
+      packet,
+      routing: {
+        requestedLane: job.modelLane,
+        selectedLane: routing.selectedLane,
+        routeMode: routing.routeMode,
+        matchedRule: routing.matchedRule,
+        reasons: routing.reasons,
+        description: routing.description || null
+      }
+    };
+  }
+
+  /**
+   * Hydrate an interactive job (Telegram message or agent dispatch) into a
+   * plan object compatible with executor.executeHydratedJob(). Unlike
+   * hydrateJob(), this does not look up a TOML job definition — it builds
+   * the plan from the raw message text and the target agent's config.
+   */
+  async hydrateInteractiveJob({ jobId, agentId, input, imageRefs = null, sessionId = null, contextLedger = null, conversationContext = null }, options = {}) {
+    const runtime = await this.loadRuntime();
+    const agent = runtime.agents[agentId];
+    if (!agent) {
+      throw new Error(`Unknown agent for interactive job ${jobId}: ${agentId}`);
+    }
+
+    if (options.shadowImport && agent.workspaceRoot) {
+      const policy = normalizePolicy(runtime.policies[`memory-${agent.memoryPolicy}`] || runtime.policies[agent.memoryPolicy]);
+      await this.bridge.importWorkspaceSnapshot(agentId, this.memoryStore, policy, {
+        workspaceOverride: agent.workspaceRoot
+      });
+    }
+
+    const objective = input;
+
+    const cacheKey = [
+      agent.soulRef || "",
+      agent.purposeRef || "",
+      agent.userRef || "",
+      (agent.workspaceContextFiles || []).join(","),
+      agent.workspaceRoot || ""
+    ].join("|");
+
+    let identity = getCached(cacheKey);
+    if (!identity) {
+      identity = await this.identityCache.get(
+        agentId,
+        { soulRef: agent.soulRef || null, purposeRef: agent.purposeRef || null, userRef: agent.userRef || null },
+        () => loadAgentIdentity(this.projectRoot, agent)
+      );
+      setCached(cacheKey, identity);
+    }
+
+    const effectiveMemoryBackends = agent.memoryBackends || ["file"];
+    const effectiveMemoryLimit = options.memoryLimit ?? 8;
+    // Interactive jobs use a conversational contract — strip completion_sections
+    // and handoff_format that force structured JSON output
+    const effectiveInteractionContract = {
+      ...resolveInteractionContract(agent.interactionContract || null, null),
+      completionSections: [],
+      handoffFormat: "conversational",
+      ackMode: "silent",
+      requiresPingback: false,
+      notifyOnDone: false,
+    };
+    const retrievalQueries = planRetrievalQueries({
+      objective,
+      taskType: "interactive",
+      purpose: identity?.purpose,
+      identity,
+    });
+
+    const modelOverride = resolveModelOverride(options.modelOverride, { routerConfig: runtime.router });
+
+    const modelId = modelOverride || runtime.router[agent.primaryLane]?.primary || "default";
+    const maxOutput = getMaxOutputTokens(modelId);
+    const contextLimit = getContextLimit(modelId);
+
+    let effectiveContext;
+    let tokenBudgetMeta = { removed: 0, estimatedTokens: 0 };
+
+    // Try Context Ledger path (Phase 3)
+    if (contextLedger && sessionId) {
+      try {
+        const { snapshot, events } = contextLedger.loadState(sessionId);
+        if (events.length > 0) {
+          const builder = new PromptBuilder({ contextLedger });
+          let systemText = `You are ${identity?.soul || agentId}. ${identity?.purpose || ""}\n\n${(identity?.contextFiles || []).map(f => `[File: ${f.name}]\n${f.content}`).join("\n\n")}`;
+          if (options && options.focusMode && options.focusMode !== "off") {
+            const focusModeInstructions = {
+              deep: "Current mode: deep work. Be terse. No preamble. No summaries. Direct answers only.",
+              planning: "Current mode: planning. Use structured bullet points and numbered lists. Surface tradeoffs."
+            };
+            const focusInstruction = focusModeInstructions[options.focusMode] || `Current mode: ${options.focusMode}.`;
+            systemText += `\n\n${focusInstruction}`;
+          }
+          if (options && options.sourceType === 'agent') {
+            const agentLabel = options.sourceAgentId || 'unknown';
+            systemText += `\n\nContext: This message is from a peer agent (${agentLabel}), not from the human operator. Reply in structured, direct format. No conversational padding. Route your reply back to the agent.`;
+          }
+          const tools = inferToolsFromPolicy(runtime.policies[`tools-${agent.toolPolicy}`] || runtime.policies[agent.toolPolicy]);
+          
+          const result = await builder.buildPrompt({
+            sessionId,
+            events,
+            snapshot,
+            systemText,
+            tools: (tools || []).map(t => ({ name: t })),
+            tokenBudgetTotal: contextLimit
+          });
+
+          effectiveContext = result.messages;
+          tokenBudgetMeta = { removed: 0, estimatedTokens: result.tokenEstimate };
+          
+          console.log(JSON.stringify({
+            service: "prompt_builder",
+            session_id: sessionId,
+            prefix_hash: result.prefixHash,
+            token_estimate: result.tokenEstimate
+          }));
+        }
+      } catch (err) {
+        console.error(JSON.stringify({ service: "prompt_builder", event: "error", error: err.message, session_id: sessionId }));
+      }
+    }
+
+    // Fallback to blob-based path
+    if (!effectiveContext && conversationContext) {
+      const parsed = JSON.parse(conversationContext);
+      const { pruned, removed, estimatedTokens } = pruneContext(parsed, contextLimit);
+      effectiveContext = pruned;
+      tokenBudgetMeta = { removed, estimatedTokens };
+    }
+
+    // Inject focus mode into identity soul for blob path
+    if (options && options.focusMode && options.focusMode !== "off") {
+      const focusModeInstructions = {
+        deep: "Current mode: deep work. Be terse. No preamble. No summaries. Direct answers only.",
+        planning: "Current mode: planning. Use structured bullet points and numbered lists. Surface tradeoffs."
+      };
+      const focusInstruction = focusModeInstructions[options.focusMode] || `Current mode: ${options.focusMode}.`;
+      identity = { ...identity, soul: (identity?.soul || "") + `\n\n${focusInstruction}` };
+    }
+
+    // Inject source context for agent-originated messages
+    if (options && options.sourceType === 'agent') {
+      const agentLabel = options.sourceAgentId || 'unknown';
+      const agentInstruction = `\n\nContext: This message is from a peer agent (${agentLabel}), not from the human operator. Reply in structured, direct format. No conversational padding. Route your reply back to the agent.`;
+      identity = { ...identity, soul: (identity?.soul || "") + agentInstruction };
+    }
+
+    console.log(JSON.stringify({
+      service: "token_budget",
+      model: modelId,
+      estimated_tokens: tokenBudgetMeta.estimatedTokens,
+      removed_turns: tokenBudgetMeta.removed,
+      max_output: maxOutput,
+    }));
+
+    const packet = await buildTaskPacket({
+      agentId,
+      objective,
+      memoryStore: this.memoryStore,
+      backendManager: this.backendManager,
+      workspaceRoot: agent.workspaceRoot,
+      backendOrder: effectiveMemoryBackends,
+      qmdSupplementLimit: agent.qmdSupplementLimit ?? 2,
+      retrievalQueries,
+      identity,
+      interactionContract: effectiveInteractionContract,
+      outputContract: null,
+      reportGuidance: null,
+      allowedTools: inferToolsFromPolicy(runtime.policies[`tools-${agent.toolPolicy}`] || runtime.policies[agent.toolPolicy]),
+      artifactRefs: [],
+      budget: { maxTokens: maxOutput, maxRuntimeSeconds: 120 },
+      memoryLimit: effectiveMemoryLimit,
+      retrievalBlend: runtime.runtime?.retrieval || null,
+      conversationContext: effectiveContext,
+    });
+    packet.modelOverride = modelOverride;
+    packet.imageRefs = imageRefs;
+    if (options.thinkMode) {
+      packet.thinkMode = options.thinkMode;
+    }
+
+    const allowedTools = inferToolsFromPolicy(runtime.policies[`tools-${agent.toolPolicy}`] || runtime.policies[agent.toolPolicy]);
+    const router = new TaskRouter(runtime.taskRouter);
+    const routing = router.choose({
+      jobId,
+      taskType: "interactive",
+      objective,
+      requestedLane: null,
+      agentPrimaryLane: agent.primaryLane,
+      outputTarget: null,
+      requiresPingback: effectiveInteractionContract.requiresPingback,
+      notifyOnDone: effectiveInteractionContract.notifyOnDone,
+      deliveryProfile: agent.delivery?.profile || null,
+      artifactRefs: [],
+      allowedTools
+    });
+
+    return {
+      job: {
+        id: jobId,
+        trigger: "interactive",
+        taskType: "interactive",
+        agentId,
+        modelLane: null,
+        outputTarget: null,
+        idempotencyKey: null,
+        liveJobHints: [],
+        budget: { maxTokens: maxOutput, maxRuntimeSeconds: 120 },
+      },
+      agent: {
+        id: agentId,
+        name: agent.name || agentId,
+        workspaceRoot: agent.workspaceRoot,
+        primaryLane: agent.primaryLane,
+        fallbackLane: agent.fallbackLane || null,
+        memoryPolicy: agent.memoryPolicy,
+        toolPolicy: agent.toolPolicy,
+        soulRef: agent.soulRef || null,
+        purposeRef: agent.purposeRef || null,
+        memoryBackendOrder: effectiveMemoryBackends,
+        memoryBackendSource: "agent",
+        qmdSupplementLimit: agent.qmdSupplementLimit ?? 2,
+        memoryLimit: effectiveMemoryLimit,
+        interactionContractSource: agent.interactionContract ? "agent" : "default",
+        interactionContract: effectiveInteractionContract,
+        deliveryProfile: agent.delivery?.profile || null,
+        memoryBackends: await this.backendManager.inspect(agentId, agent.workspaceRoot),
+        reportGuidance: null,
+        retrievalBlend: runtime.runtime?.retrieval || null,
+        execApprovals: agent.execApprovals ?? false,
+      },
+      packet,
+      routing: {
+        requestedLane: null,
+        selectedLane: routing.selectedLane,
+        routeMode: routing.routeMode,
+        matchedRule: routing.matchedRule,
+        reasons: routing.reasons,
+        description: routing.description || null
+      }
+    };
+  }
+
+  async summarizeLiveCron() {
+    const jobs = await this.bridge.loadCronJobs();
+    return jobs.map((job) => ({
+      id: job.id,
+      name: job.name,
+      description: job.description || null,
+      enabled: job.enabled,
+      schedule: job.schedule,
+      targetModel: job.payload?.model || null,
+      timeoutSeconds: job.payload?.timeoutSeconds || null,
+      kind: job.payload?.kind || null,
+      messagePreview: String(job.payload?.message || job.payload?.text || "").slice(0, 160),
+      lastStatus: job.state?.lastStatus || null,
+      consecutiveErrors: job.state?.consecutiveErrors || 0
+    }));
+  }
+
+  async compareJobs() {
+    const [v2Jobs, liveJobs] = await Promise.all([this.listJobPlans(), this.summarizeLiveCron()]);
+
+    return v2Jobs.map((job) => ({
+      v2JobId: job.id,
+      v2TaskType: job.taskType,
+      v2Trigger: job.trigger,
+      liveJobHints: job.liveJobHints,
+      closestLiveJobs: liveJobs
+        .map((liveJob) => ({
+          ...liveJob,
+          _score: compareJobText(job, liveJob)
+        }))
+        .filter((liveJob) => liveJob._score > 0)
+        .sort((a, b) => b._score - a._score)
+        .slice(0, 3)
+        .map(({ _score, ...liveJob }) => liveJob)
+    }));
+  }
+}
+
+function normalizeOutputContract(contract, outputContracts = null) {
+  const defaultProfile = outputContracts?.profiles?.default || null;
+  if (!contract) {
+    if (!defaultProfile) return null;
+    return {
+      format: null,
+      requiredSections: [],
+      styleHints: [],
+      profile: {
+        requireStatus: defaultProfile.requireStatus ?? false,
+        sectionStyle: defaultProfile.sectionStyle || "bullets",
+        requireSectionItems: defaultProfile.requireSectionItems ?? true,
+        templateLines: defaultProfile.templateLines || []
+      }
+    };
+  }
+  const profileKey = String(contract.format || "").replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+  const profile = outputContracts?.profiles?.[profileKey] || defaultProfile || null;
+  return {
+    format: contract.format || null,
+    requiredSections: contract.requiredSections || [],
+    styleHints: contract.styleHints || [],
+    profile: profile
+      ? {
+          requireStatus: profile.requireStatus ?? false,
+          sectionStyle: profile.sectionStyle || "bullets",
+          requireSectionItems: profile.requireSectionItems ?? true,
+          templateLines: profile.templateLines || []
+        }
+      : null
+  };
+}
+
+function normalizeReportGuidance(reportGuidance) {
+  if (!reportGuidance) return null;
+  return {
+    focus: reportGuidance.focus || [],
+    qualityChecks: reportGuidance.qualityChecks || [],
+    avoid: reportGuidance.avoid || []
+  };
+}
+
+async function loadAgentIdentity(projectRoot, agent) {
+  const cacheKey = [
+    agent.soulRef || "",
+    agent.purposeRef || "",
+    agent.userRef || "",
+    (agent.workspaceContextFiles || []).join(","),
+    agent.workspaceRoot || ""
+  ].join("|");
+
+  const cached = getCached(cacheKey);
+  if (cached) {
+    console.log(`[identity-cache] hit for agent ${agent.id || "unknown"}`);
+    return cached;
+  }
+
+  console.log(`[identity-cache] miss — loading from disk for agent ${agent.id || "unknown"}`);
+
+  const soul = await readOptionalIdentity(projectRoot, agent.soulRef);
+  const purpose = await readOptionalIdentity(projectRoot, agent.purposeRef);
+  const user = await readOptionalIdentity(projectRoot, agent.userRef);
+
+  // Load workspace context files (MEMORY.md, AGENTS.md, etc.) relative to workspace_root
+  const contextFiles = [];
+  if (agent.workspaceRoot && agent.workspaceContextFiles?.length) {
+    const cap = agent.workspaceContextCap ?? 8000;
+    for (const filename of agent.workspaceContextFiles) {
+      const filePath = path.join(agent.workspaceRoot, filename);
+      const content = await readText(filePath, null);
+      if (content) {
+        const capped = content.length > cap ? content.slice(0, cap) + `\n\n[truncated — full file at ${filePath}]` : content;
+        contextFiles.push({ name: filename, content: capped });
+      }
+    }
+  }
+
+  const result = (!soul && !purpose && !user && contextFiles.length === 0)
+    ? null
+    : {
+        soul,
+        purpose,
+        user,
+        contextFiles
+      };
+
+  setCached(cacheKey, result);
+  return result;
+}
+
+async function readOptionalIdentity(projectRoot, ref) {
+  if (!ref) return null;
+  return readText(path.isAbsolute(ref) ? ref : path.join(projectRoot, ref), null);
+}
+
+function inferToolsFromPolicy(policy) {
+  return policy?.allowed || [];
+}
+
+function compareJobText(v2Job, liveJob) {
+  const haystack = `${liveJob.name || ""} ${liveJob.description || ""} ${liveJob.id || ""} ${liveJob.kind || ""} ${liveJob.messagePreview || ""}`.toLowerCase();
+  const stopwords = new Set(["check", "job", "task", "run", "daily", "hourly", "every", "rollup", "health"]);
+  const needles = [...v2Job.taskType.split("_"), ...v2Job.id.split("-")].filter(
+    (token) => token.length > 2 && !stopwords.has(token.toLowerCase())
+  );
+  let score = 0;
+  for (const token of needles) {
+    if (haystack.includes(token.toLowerCase())) score += 1;
+  }
+  for (const hint of v2Job.liveJobHints || []) {
+    if (haystack.includes(String(hint).toLowerCase())) score += 3;
+  }
+  return score;
+}