@vantran-se/openchamber-web 2.1.1 → 2.2.0

package/server/lib/routing/cache.js

@@ -0,0 +1,87 @@
+/**
+ * "Try to preserve cache usage". A provider keeps a prompt cache per model, so
+ * switching models mid-session makes the new model read the whole context
+ * uncached, and the old model's cache goes cold while the session is away from
+ * it. While the model that wrote the last answer likely still holds a warm
+ * cache, Auto stays on it instead of moving down to a lower category; moving up
+ * is never held back.
+ *
+ * "Lower" is the built-in category order: trivial < research < implement <
+ * hard. Categories the user added have no place in that order, so a send routed
+ * to one of them switches as it always did.
+ */
+import { z } from 'zod';
+import { BUILTIN_CATEGORIES } from './defaults.js';
+
+/** How long a provider keeps a prompt cache after its last use. */
+export const PROMPT_CACHE_TTL_MS = 5 * 60 * 1000;
+
+/** OpenCode's warming `duration` when the config says only `true` (core `plugin/warming.ts`). */
+const DEFAULT_WARMING_DURATION_MS = 30 * 60 * 1000;
+
+const RANK = new Map(BUILTIN_CATEGORIES.map((category, index) => [category.id, index]));
+
+const rankOf = (category) => (category.builtin ? RANK.get(category.id) ?? null : null);
+
+const sameModel = (a, b) => a.providerID === b.providerID && a.modelID === b.modelID;
+
+/**
+ * The category Auto keeps instead of `chosen`, or null to switch as Jev said.
+ * `current` is the model that wrote the session's last answer. Several
+ * categories can share that model; the highest of them is where the session
+ * is, so a choice below it is a move down. Only a category that runs the same
+ * agent as `chosen` is kept: another agent sends another system prompt, which
+ * misses the cache anyway, and would run the request with tools it did not ask
+ * for (a planning agent for an edit).
+ */
+export const cacheHoldCategory = ({ categories, fallback, composerAgent, chosen, current }) => {
+  const chosenRank = chosen ? rankOf(chosen) : null;
+  if (chosenRank === null || !current) return null;
+  const modelOf = (category) => category.model ?? fallback.model;
+  const agentOf = (category) => category.agent || composerAgent || null;
+  if (sameModel(modelOf(chosen), current)) return null;
+  let held = null;
+  for (const category of categories) {
+    const rank = rankOf(category);
+    if (rank === null || !sameModel(modelOf(category), current) || agentOf(category) !== agentOf(chosen)) continue;
+    if (!held || rank > rankOf(held)) held = category;
+  }
+  return held && rankOf(held) > chosenRank ? held : null;
+};
+
+const DURATION = /^(\d+(?:\.\d+)?)\s*([a-z]+)$/i;
+const UNIT_MS = {
+  ms: 1, millis: 1, millisecond: 1, milliseconds: 1,
+  s: 1000, second: 1000, seconds: 1000,
+  m: 60_000, minute: 60_000, minutes: 60_000,
+  h: 3_600_000, hour: 3_600_000, hours: 3_600_000,
+};
+
+/** OpenCode answers a duration as `"1800000 millis"`; a hand-written `"30 minutes"` reads too. */
+const durationMs = (text) => {
+  const match = DURATION.exec(text.trim());
+  const unit = match ? UNIT_MS[match[2].toLowerCase()] : undefined;
+  const ms = unit ? Number(match[1]) * unit : NaN;
+  return Number.isFinite(ms) && ms > 0 ? ms : null;
+};
+
+const warmingSchema = z.union([z.boolean(), z.object({ duration: z.string().optional() })]);
+const configEntriesSchema = z.array(z.object({ info: z.object({ warming: warmingSchema.optional() }).nullish() }));
+
+/**
+ * How long after its last answer a session's cache stays warm, from the config
+ * entries OpenCode answers for the directory (lowest priority first, the last
+ * one that sets `warming` wins, as OpenCode reads it). With warming on,
+ * OpenCode pings the model until `duration` after the last turn, and the last
+ * ping keeps the cache one more lifetime. Entries this cannot read count as
+ * warming off: holding a model on a cache that went cold is the costlier
+ * mistake.
+ */
+export const warmWindowMs = (configEntries) => {
+  const parsed = configEntriesSchema.safeParse(configEntries);
+  if (!parsed.success) return PROMPT_CACHE_TTL_MS;
+  const warming = parsed.data.findLast((entry) => entry.info?.warming !== undefined)?.info.warming;
+  if (!warming) return PROMPT_CACHE_TTL_MS;
+  const duration = warming === true || !warming.duration ? null : durationMs(warming.duration);
+  return (duration ?? DEFAULT_WARMING_DURATION_MS) + PROMPT_CACHE_TTL_MS;
+};

package/server/lib/routing/defaults.js

@@ -79,11 +79,20 @@ export const JEV_TIMEOUT_MS = 4000;
  * request refers to, and that finished work carries no weight, put them at
  * 97% and ~75% trivial while "ok, do it" after a plan stayed implement and a
  * regression report stayed hard (jev-router lab, test/follow-up-instructions.js).
+ *
+ * The fourth line covers a bare approval, which the third would otherwise
+ * read as trivial: "go" after a plan carries no work of its own, so it takes
+ * the category of the work it approves (the #4374 author measured this on
+ * their own prompts; not yet replayed in the jev-router lab).
+ * It does not let finished work raise a follow-up; a follow-up that only
+ * looks cheap because it reuses a warm context is the router's concern, not
+ * the classifier's.
  */
 export const ROUTING_INSTRUCTIONS = [
   'Pick the task category that best describes this coding request, judging the reasoning it demands rather than the length of the reply it asks for.',
   'A request that wants a one-line answer to a hard debugging or design question is still hard; a long but mechanical edit is still trivial.',
   'The thing to classify is `request`, the latest user message. Read `history` (earlier conversation, oldest first) only to understand what `request` refers to, then judge the reasoning `request` itself demands. Do not let the difficulty of work already done in `history` raise or lower the category.',
+  'A bare approval such as "go", "yes", "approve", or "do it" authorises the work just described in history: classify it as the category that work demands, not as trivial.',
 ];
 
 /**
@@ -139,4 +148,6 @@ export const BUILTIN_CATEGORIES = [
 ];
 
 export const DEFAULT_MIN_CONFIDENCE = 0.6;
+/** "Try to preserve cache usage" (`cache.js`) is on unless the user turned it off. */
+export const DEFAULT_PRESERVE_CACHE = true;
 export const DEFAULT_SAFETY_THRESHOLD = 0.6;

package/server/lib/routing/history.js

@@ -23,12 +23,20 @@ export const turnsToHistory = (turns, limits = HISTORY_LIMITS) => {
   return history;
 };
 
+/** The model that wrote a settled answer and when it finished, or null when the record lacks either. */
+const answeredBy = (message) => (message?.providerID && message.modelID && message.completed
+  ? { providerID: message.providerID, modelID: message.modelID, completed: message.completed }
+  : null);
+
 /**
- * Empty when the session has no settled answer yet (a new session, or one
- * interrupted mid-turn) — routing then judges the request on its own. A read
- * failure is thrown so the caller can decide; it is not an empty history.
+ * `history` is empty and `lastAnswer` null when the session has no settled
+ * answer yet (a new session, or one interrupted mid-turn): routing then judges
+ * the request on its own and has no cache to preserve. A read failure is
+ * thrown so the caller can decide; it is not an empty history.
  */
 export const loadRoutingHistory = async ({ readPage, signal }) => {
   const context = await loadAssistContext({ readPage, signal });
-  return context ? turnsToHistory(context.turns) : [];
+  return context
+    ? { history: turnsToHistory(context.turns), lastAnswer: answeredBy(context.last) }
+    : { history: [], lastAnswer: null };
 };

package/server/lib/routing/runtime.js

@@ -26,6 +26,7 @@ import {
   resolveClassifier,
 } from './classifier.js';
 import { loadRoutingHistory } from './history.js';
+import { PROMPT_CACHE_TTL_MS, cacheHoldCategory, warmWindowMs } from './cache.js';
 import { readOpenCodeCredentials } from '../opencode/auth.js';
 import { ENTERPRISE_MODE_ERROR, isEnterpriseMode } from '../enterprise-mode.js';
 
@@ -122,6 +123,8 @@ export function createRoutingRuntime({
   enterpriseMode = isEnterpriseMode,
   readPinnedEndpoint = readPinnedCustomEndpoint,
   listCatalogModels = null,
+  readSessionHistory = null,
+  readConfigEntries = null,
   now = Date.now,
 }) {
   const permissionDecisions = new Map();
@@ -220,7 +223,7 @@ export function createRoutingRuntime({
     return OpenCode.make({ baseUrl: buildOpenCodeUrl('/', '').replace(/\/$/, ''), headers });
   };
 
-  const readHistory = async ({ sessionId, directory }) => {
+  const readHistory = readSessionHistory ?? (async ({ sessionId, directory }) => {
     const client = openCodeClient(directory);
     const signal = AbortSignal.timeout(HISTORY_TIMEOUT_MS);
     return loadRoutingHistory({
@@ -231,6 +234,31 @@ export function createRoutingRuntime({
         { signal },
       ),
     });
+  });
+
+  // v2 answers the effective config as its documents, lowest priority first.
+  const readConfig = readConfigEntries ?? ((directory) => openCodeClient(directory).config.get());
+
+  /**
+   * "Try to preserve cache usage": the category to stay on instead of a lower
+   * one while the model that wrote the last answer likely still holds a warm
+   * prompt cache, or null to switch as Jev said (`cache.js`). OpenCode's
+   * warming config is read only once the plain cache lifetime has passed.
+   */
+  const cacheHold = async ({ config, chosen, composerAgent, lastAnswer, directory }) => {
+    if (!config.preserveCache || !lastAnswer) return null;
+    const held = cacheHoldCategory({
+      categories: enabledCategories(config), fallback: config.fallback, composerAgent, chosen, current: lastAnswer,
+    });
+    if (!held) return null;
+    const idle = now() - lastAnswer.completed;
+    if (idle < PROMPT_CACHE_TTL_MS) return held;
+    try {
+      return idle < warmWindowMs(await readConfig(directory)) ? held : null;
+    } catch (error) {
+      console.warn('[routing] OpenCode config unavailable, treating the prompt cache as cold:', errorMessage(error));
+      return null;
+    }
   };
 
   // A category without a model of its own means "the fallback pair"; a variant
@@ -300,8 +328,9 @@ export function createRoutingRuntime({
     let selection;
     if (state.autoReady) {
       let history = [];
+      let lastAnswer = null;
       try {
-        history = await readHistory({ sessionId, directory });
+        ({ history, lastAnswer } = await readHistory({ sessionId, directory }));
       } catch (error) {
         console.warn('[routing] history unavailable, routing on the request alone:', errorMessage(error));
       }
@@ -315,7 +344,14 @@ export function createRoutingRuntime({
         decision.confidence = result.confidence;
         decision.reason = result.reason;
         decision.ms = ms;
-        selection = chooseSelection(config, result.category, agent);
+        const held = await cacheHold({ config, chosen: result.category, composerAgent: agent, lastAnswer, directory });
+        if (held) {
+          // The send runs as the category the session is already on;
+          // `cacheHold.requested` keeps what Jev asked for.
+          decision.category = held.id;
+          decision.cacheHold = { requested: result.category.id };
+        }
+        selection = chooseSelection(config, held ?? result.category, agent);
       } catch (error) {
         decision.reason = 'error';
         decision.error = errorMessage(error);

package/server/lib/routing/runtime.test.js

@@ -19,7 +19,10 @@ const readyConfig = () => {
   return config;
 };
 
-const makeRuntime = ({ config = readyConfig(), token = 'key', classifierSource = null, customEndpoint = null, providerKeys = {}, zenPromotionActive = true, enterprise = false, pinned = null, catalog = [], answers, askError } = {}) => {
+const makeRuntime = ({
+  config = readyConfig(), token = 'key', classifierSource = null, customEndpoint = null, providerKeys = {}, zenPromotionActive = true,
+  enterprise = false, pinned = null, catalog = [], answers, askError, lastAnswer = null, configEntries = [], nowMs = 1_000_000_000,
+} = {}) => {
   const events = [];
   const store = {
     readConfig: vi.fn(async () => config),
@@ -34,6 +37,10 @@ const makeRuntime = ({ config = readyConfig(), token = 'key', classifierSource =
     clearCustomEndpoint: vi.fn(async () => undefined),
   };
   const jev = { ask: vi.fn(async () => { if (askError) throw askError; return { answers, ms: 12 }; }) };
+  const readConfigEntries = vi.fn(async () => {
+    if (configEntries instanceof Error) throw configEntries;
+    return configEntries;
+  });
   const runtime = createRoutingRuntime({
     dataDir: '/unused',
     buildOpenCodeUrl: () => 'http://127.0.0.1:1/',
@@ -49,8 +56,11 @@ const makeRuntime = ({ config = readyConfig(), token = 'key', classifierSource =
       if (catalog instanceof Error) throw catalog;
       return catalog;
     },
+    readSessionHistory: async () => ({ history: [], lastAnswer }),
+    readConfigEntries,
+    now: () => nowMs,
   });
-  return { runtime, store, jev, events };
+  return { runtime, store, jev, events, readConfigEntries };
 };
 
 describe('requestTextOf', () => {
@@ -173,6 +183,75 @@ describe('resolveAutoSelection', () => {
   });
 });
 
+describe('preserving the prompt cache', () => {
+  const NOW = 1_000_000_000;
+  const MINUTE = 60_000;
+  const HARD = { providerID: 'openai', modelID: 'gpt-6-astra' };
+  // Hard on its own model and the composer's agent, so only the model differs.
+  const cacheConfig = () => {
+    const config = readyConfig();
+    config.categories = config.categories.map((c) => (c.id === 'hard' ? { ...c, agent: null } : c));
+    return config;
+  };
+  const answeredBy = (model, minutesAgo) => ({ ...model, completed: NOW - minutesAgo * MINUTE });
+  const route = async ({ choice, config = cacheConfig(), lastAnswer, configEntries, agent = 'build' }) => {
+    const made = makeRuntime({ config, lastAnswer, configEntries, nowMs: NOW, answers: { category: { choice, confidence: 0.95 } } });
+    const resolved = await made.runtime.resolveAutoSelection({ sessionId: 's1', model: AUTO, agent, requestText: 'push it' });
+    return { ...made, resolved };
+  };
+
+  it('stays on the warm model instead of moving down, and records what Jev asked for', async () => {
+    const { resolved, readConfigEntries } = await route({ choice: 'trivial', lastAnswer: answeredBy(HARD, 2) });
+    expect(resolved.model).toEqual({ providerID: 'openai', id: 'gpt-6-astra', variant: 'high' });
+    expect(resolved.agent).toBe('build');
+    expect(resolved.decision).toMatchObject({ category: 'hard', reason: 'routed', cacheHold: { requested: 'trivial' } });
+    expect(readConfigEntries).not.toHaveBeenCalled();
+  });
+
+  it('moves down once the cache has expired, and moves up at any time', async () => {
+    const cold = await route({ choice: 'trivial', lastAnswer: answeredBy(HARD, 6) });
+    expect(cold.resolved.model).toMatchObject({ providerID: 'anthropic', id: 'claude-sonnet-5' });
+    expect(cold.resolved.decision.cacheHold).toBeUndefined();
+
+    const up = await route({ choice: 'hard', lastAnswer: answeredBy(FALLBACK.model, 1) });
+    expect(up.resolved.model).toMatchObject({ providerID: 'openai', id: 'gpt-6-astra' });
+  });
+
+  it("counts OpenCode's session warming: its duration plus one cache lifetime", async () => {
+    const warming = [{ info: { model: 'anthropic/claude-sonnet-5' } }, { info: { warming: true } }];
+    expect((await route({ choice: 'trivial', lastAnswer: answeredBy(HARD, 20), configEntries: warming })).resolved.decision.category).toBe('hard');
+    expect((await route({ choice: 'trivial', lastAnswer: answeredBy(HARD, 36), configEntries: warming })).resolved.decision.category).toBe('trivial');
+
+    const hour = [{ info: { warming: { duration: '3600000 millis' } } }];
+    expect((await route({ choice: 'trivial', lastAnswer: answeredBy(HARD, 50), configEntries: hour })).resolved.decision.category).toBe('hard');
+
+    const turnedOff = [{ info: { warming: true } }, { info: { warming: false } }];
+    expect((await route({ choice: 'trivial', lastAnswer: answeredBy(HARD, 20), configEntries: turnedOff })).resolved.decision.category).toBe('trivial');
+  });
+
+  it('treats the cache as cold when the OpenCode config cannot be read', async () => {
+    const { resolved } = await route({ choice: 'trivial', lastAnswer: answeredBy(HARD, 20), configEntries: new Error('OpenCode down') });
+    expect(resolved.decision.category).toBe('trivial');
+  });
+
+  it('switches as before with the setting off, for a category of the user, or when the agent would change', async () => {
+    const off = cacheConfig();
+    off.preserveCache = false;
+    expect((await route({ choice: 'trivial', config: off, lastAnswer: answeredBy(HARD, 1) })).resolved.decision.category).toBe('trivial');
+
+    const own = cacheConfig();
+    own.categories.push({ id: 'docs', builtin: false, enabled: true, name: 'Docs', description: 'Docs', model: null, variant: null, agent: null });
+    expect((await route({ choice: 'docs', config: own, lastAnswer: answeredBy(HARD, 1) })).resolved.decision.category).toBe('docs');
+
+    // readyConfig's hard category runs the plan agent.
+    expect((await route({ choice: 'trivial', config: readyConfig(), lastAnswer: answeredBy(HARD, 1) })).resolved.decision.category).toBe('trivial');
+  });
+
+  it('switches when the session has no settled answer to have warmed a cache', async () => {
+    expect((await route({ choice: 'trivial', lastAnswer: null })).resolved.decision.category).toBe('trivial');
+  });
+});
+
 describe('jev endpoint', () => {
   const capture = async (source, keys = {}) => {
     let call = null;

package/server/lib/routing/store.js

@@ -20,6 +20,7 @@ import { z } from 'zod';
 import {
   BUILTIN_CATEGORIES,
   DEFAULT_MIN_CONFIDENCE,
+  DEFAULT_PRESERVE_CACHE,
   DEFAULT_SAFETY_THRESHOLD,
   THINKING_LEVELS,
   isAutoModel,
@@ -66,6 +67,7 @@ const fileSchema = z.object({
   enabled: z.boolean().optional(),
   fallback: z.object({ model: modelSchema, variant: variantSchema.optional() }).strict().nullable().optional(),
   minConfidence: z.number().min(0).max(1).optional(),
+  preserveCache: z.boolean().optional(),
   safetyNet: z.object({ enabled: z.boolean(), threshold: z.number().min(0).max(1) }).strict().optional(),
   categories: z.record(z.string().regex(CATEGORY_ID), z.discriminatedUnion('builtin', [builtinOverrideSchema, userCategorySchema])).optional(),
 }).strict();
@@ -86,6 +88,8 @@ const effectiveConfigSchema = z.object({
   enabled: z.boolean(),
   fallback: z.object({ model: modelSchema, variant: variantSchema }).strict().nullable(),
   minConfidence: z.number().min(0).max(1),
+  // Clients from before the setting send a config without it.
+  preserveCache: z.boolean().default(DEFAULT_PRESERVE_CACHE),
   safetyNet: z.object({ enabled: z.boolean(), threshold: z.number().min(0).max(1) }).strict(),
   categories: z.array(effectiveCategorySchema).max(32),
 }).strict();
@@ -178,6 +182,7 @@ export const resolveEffectiveConfig = (stored) => {
     enabled: file.enabled ?? false,
     fallback: file.fallback ? { model: file.fallback.model, variant: file.fallback.variant ?? null } : null,
     minConfidence: file.minConfidence ?? DEFAULT_MIN_CONFIDENCE,
+    preserveCache: file.preserveCache ?? DEFAULT_PRESERVE_CACHE,
     safetyNet: file.safetyNet ?? { enabled: false, threshold: DEFAULT_SAFETY_THRESHOLD },
     categories,
   };
@@ -214,7 +219,13 @@ export const toStoredConfig = (config) => {
   for (const builtin of BUILTIN_CATEGORIES) {
     if (!present.has(builtin.id)) categories[builtin.id] = { builtin: true, deleted: true };
   }
-  const stored = { version: FILE_VERSION, enabled: config.enabled, minConfidence: config.minConfidence, safetyNet: config.safetyNet };
+  const stored = {
+    version: FILE_VERSION,
+    enabled: config.enabled,
+    minConfidence: config.minConfidence,
+    preserveCache: config.preserveCache,
+    safetyNet: config.safetyNet,
+  };
   if (config.fallback) {
     stored.fallback = { model: config.fallback.model };
     if (config.fallback.variant) stored.fallback.variant = config.fallback.variant;

package/server/lib/routing/store.test.js

@@ -11,6 +11,7 @@ const sampleConfig = (patch = {}) => ({
   enabled: true,
   fallback: { model: { providerID: 'anthropic', modelID: 'claude-sonnet-5' }, variant: 'medium' },
   minConfidence: 0.6,
+  preserveCache: true,
   safetyNet: { enabled: true, threshold: 0.6 },
   categories: resolveEffectiveConfig(null).categories,
   ...patch,
@@ -44,6 +45,18 @@ describe('routing store', () => {
     expect(await store.readConfig()).toEqual(config);
   });
 
+  it('keeps the cache setting on until it is turned off, also for clients that do not send it', async () => {
+    expect(resolveEffectiveConfig(null).preserveCache).toBe(true);
+    expect(resolveEffectiveConfig({ version: 1, enabled: true }).preserveCache).toBe(true);
+
+    const store = createRoutingStore({ dataDir: await tempDir() });
+    await store.writeConfig(sampleConfig({ preserveCache: false }));
+    expect((await store.readConfig()).preserveCache).toBe(false);
+
+    const { preserveCache: _omitted, ...older } = sampleConfig();
+    expect(parseEffectiveConfig(older).preserveCache).toBe(true);
+  });
+
   it('records a removed built-in as deleted and keeps the others', async () => {
     const config = sampleConfig();
     config.categories = config.categories.filter((c) => c.id !== 'research');

package/server/lib/scheduled-tasks/DOCUMENTATION.md

@@ -100,6 +100,55 @@ Manual `runNow` does not claim a schedule occurrence. It also runs paused
 (`enabled: false`) tasks — that is the point of the button — while scheduled
 dispatches still skip disabled tasks, and completion never re-arms a paused task.
 
+## Existing-session tasks
+
+`targetSessionId` sends to an existing session instead of creating one.
+`existing-session.js` validates changed or enabled targets on save, and all
+targets on admission and send. A paused task can keep a stale target. The
+target must be active and belong to the task project or its linked worktree.
+Another registered project owns its exact checkout. Chats targets must remain
+inside the chats scope. Missing targets return 404; archived or foreign targets
+return 409, including through Run now.
+
+The prompt enters the ordinary server message queue with `scheduledTask`
+provenance. One project and task can have at most one waiting prompt. Run now
+on an already queued prompt records `skipped` and returns 409 with
+`busy: queued`. Admission sets `lastSessionId` to the target. Disable, delete
+and retarget cancel waiting prompts, but cannot recall a send already in flight.
+Saving an already-paused task with the same target keeps a prompt admitted by
+Run now. Cancellation on disable applies only to an enabled-to-disabled change.
+Scheduled once tasks are disabled after an admission attempt, including a
+failed attempt. An admitted prompt stays queued. Run now can still admit a
+paused task.
+
+An overlapping admission attempt records `skipped` before the active admission
+records `queued`. A later duplicate enqueue records `skipped` while the earlier
+prompt remains waiting. The card shows the last attempt's status in that case.
+
+Reuse status ends at queue send: `queued` becomes `sent`, `failed` or
+`cancelled`. The existing task state fields hold the result. There is no
+per-run history or assistant-completion tracking. `execution.useDefaults`
+leaves the target model and agent unchanged. A pinned selection switches the
+requested model and agent before sending. Tasks without a target keep the
+new-session execution path below.
+
+Reuse preserves the target's goal and permission auto-accept policy. Task
+creation options for these policies are hidden in Existing mode and ignored
+by the reuse runtime. Transient queue send failures use the ordinary retry
+policy. Only definitive before-send target or task 404 or 409 refusals are
+terminal, including removed or retargeted tasks and moved targets. Model or
+prompt send errors use the ordinary retry path.
+
+## New-session selection
+
+A task either pins them (`execution.providerID`, `modelID`, `variant`, `agent`)
+or sets `execution.useDefaults: true`. Such a task reads the session defaults
+when each run starts (`session-defaults.js`: the project's `defaultModel` /
+`defaultVariant` / `defaultAgent`, then the global ones), so changing a default
+reaches it on its next run without editing it. With nothing set, the session is
+created without a model or agent and OpenCode applies its own. A pinned value
+stored next to `useDefaults` is kept only for when the task is pinned again.
+
 ## Files
 
 - `packages/web/server/lib/scheduled-tasks/runtime.js`
@@ -193,7 +242,16 @@ project write lock on every `syncProject` when the project path is known:
   name, schedule and execution. Enabling a loop in the UI (the loop-file
   endpoint) records that approval; disabling withdraws it. A pull that changes
   what a loop runs or when changes its fingerprint, and the loop waits for a
-  new approval. User-scope loops (`~/.agents/loops`) need none.
+  new approval. User-scope loops (`~/.agents/loops`) need none. A task the
+  gate holds back is returned with `loopApproval`: `required` (never enabled
+  here) or `outdated` (enabled, then the file changed); the UI explains the
+  pause from it. The field is never stored.
+- **Agent tool and CLI.** `setEnabled` (behind `schedule.toggle` and
+  `openchamber schedule enable|disable`) changes a loop task the way the
+  Scheduled tasks checkbox does, through the loop file. It refuses (409) to
+  enable a paused project-scope loop: the approval is the user's decision in
+  Scheduled tasks, never an agent's or a script's. Disabling works for every
+  loop.
 - **Loop-file mutations.** The loop file remains authoritative. The scheduled-
   tasks UI opens it in the built-in file editor, updates its `enabled`
   frontmatter through the loop-file endpoint, and deletes the file through the

package/server/lib/scheduled-tasks/existing-session.js

@@ -0,0 +1,119 @@
+import path from 'node:path';
+import { z } from 'zod';
+import { OpenChamberControlError } from '../openchamber-control/error.js';
+import { expandSnippets } from '../opencode/snippets.js';
+
+export const createExistingSessionTasks = ({ projectConfigRuntime, messageQueueRuntime, createClient, listProjects, chatsScope, resolvePrimaryWorktreeRoot, isSessionArchived, emitTaskRunEvent }) => {
+  const admissions = new Set();
+  const validateTarget = async (projectId, targetSessionId) => {
+    if (!z.string().regex(/^[A-Za-z0-9_-]{4,128}$/).safeParse(targetSessionId).success) {
+      throw new OpenChamberControlError('targetSessionId is invalid', 400);
+    }
+    if (await isSessionArchived?.(targetSessionId)) throw new OpenChamberControlError('Scheduled target is archived', 409);
+    let session;
+    try {
+      session = await createClient('').session.get({ sessionID: targetSessionId });
+    } catch (error) {
+      if (error?.name === 'NotFoundError' || error?.status === 404 || error?.statusCode === 404) throw new OpenChamberControlError('Scheduled target not found', 404);
+      throw error;
+    }
+    if (!session?.id) throw new OpenChamberControlError('Scheduled target not found', 404);
+    if (session.id !== targetSessionId) throw new OpenChamberControlError('Scheduled target identity mismatch', 409);
+    if (session.time?.archived) throw new OpenChamberControlError('Scheduled target is archived', 409);
+    const projects = await listProjects();
+    const project = projects.find((entry) => entry.id === projectId);
+    const directory = session.location?.directory;
+    if (!directory) throw new OpenChamberControlError('Scheduled target has no directory', 409);
+    if (projects.some((entry) => entry.id !== projectId && path.resolve(entry.path) === path.resolve(directory))) {
+      throw new OpenChamberControlError('Scheduled target belongs to another project', 409);
+    }
+    let belongs = false;
+    if (chatsScope && projectId === chatsScope.id) belongs = chatsScope.contains(directory);
+    else if (project && directory) {
+      belongs = path.resolve(directory) === path.resolve(project.path);
+      if (!belongs && resolvePrimaryWorktreeRoot) {
+        const owner = await resolvePrimaryWorktreeRoot(directory);
+        belongs = Boolean(owner?.root) && path.resolve(owner.root) === path.resolve(project.path);
+      }
+    }
+    if (!belongs) throw new OpenChamberControlError('Scheduled target is outside the task project', 409);
+    return { session, directory };
+  };
+
+  const record = async (projectId, taskId, status, error, lastRunAt) => {
+    const patch = {
+      lastStatus: status, lastError: error || undefined, updatedAt: Date.now(),
+    };
+    if (lastRunAt !== undefined) patch.lastRunAt = lastRunAt;
+    const result = await projectConfigRuntime.updateScheduledTaskState(projectId, taskId, patch);
+    emitTaskRunEvent?.({ projectID: projectId, taskID: taskId, status, ranAt: Date.now(), sessionID: result.task?.state?.lastSessionId });
+    return result.task;
+  };
+
+  const run = async (projectId, task, reason, scheduledFor, nextRunAt) => {
+    const triggeredAt = Date.now();
+    const key = `${projectId}:${task.id}`;
+    if (admissions.has(key)) {
+      try {
+        await record(projectId, task.id, 'skipped', 'task is already queued');
+      } catch (persistError) {
+        console.warn('[scheduled-tasks] admission failure state write failed:', persistError?.message);
+      }
+      return { ok: false, queued: true, error: 'task is already queued' };
+    }
+    admissions.add(key);
+    let admitted = false;
+    try {
+      if (reason === 'scheduled') {
+        const claim = await projectConfigRuntime.updateScheduledTaskStateIf(projectId, task.id,
+          (candidate) => candidate.enabled && (!Number.isFinite(candidate.state?.lastScheduledFor) || Math.abs(candidate.state.lastScheduledFor - scheduledFor) > 5_000),
+          { lastScheduledFor: scheduledFor, nextRunAt: nextRunAt ?? undefined });
+        if (!claim.updated) return { ok: false, skipped: true };
+      }
+      const { directory } = await validateTarget(projectId, task.targetSessionId);
+      const sendConfig = task.execution.useDefaults ? {} : {
+        providerID: task.execution.providerID, modelID: task.execution.modelID,
+        agent: task.execution.agent, variant: task.execution.variant,
+      };
+      const scheduledTask = { projectId, taskId: task.id };
+      await messageQueueRuntime.enqueue(task.targetSessionId, directory, {
+        content: task.execution.prompt,
+        text: expandSnippets(task.execution.prompt, directory),
+        sendConfig, scheduledTask,
+      });
+      admitted = true;
+      const result = await projectConfigRuntime.updateScheduledTaskState(projectId, task.id, {
+        lastRunAt: triggeredAt, lastStatus: 'queued', lastError: undefined,
+        lastSessionId: task.targetSessionId, updatedAt: Date.now(),
+      });
+      emitTaskRunEvent?.({ projectID: projectId, taskID: task.id, status: 'queued', ranAt: Date.now(), sessionID: task.targetSessionId });
+      return { ok: true, task: result.task, sessionID: task.targetSessionId, directory };
+    } catch (error) {
+      if (admitted) await messageQueueRuntime.cancelScheduledTask(projectId, task.id);
+      const queued = error?.status === 409 && error.message === 'task is already queued';
+      let updated = task;
+      try {
+        updated = await record(projectId, task.id, queued ? 'skipped' : 'failed', error.message, triggeredAt);
+      } catch (persistError) {
+        console.warn('[scheduled-tasks] admission failure state write failed:', persistError?.message);
+      }
+      return { ok: false, queued, error: error.message, statusCode: error.statusCode ?? error.status, task: updated };
+    } finally {
+      admissions.delete(key);
+    }
+  };
+
+  const beforeSend = async (sessionId, directory, item) => {
+    const { projectId, taskId } = item.scheduledTask;
+    const task = (await projectConfigRuntime.listScheduledTasks(projectId)).find((entry) => entry.id === taskId);
+    if (!task || task.targetSessionId !== sessionId) throw new OpenChamberControlError('Scheduled task target changed or was removed', 409);
+    const target = await validateTarget(projectId, sessionId);
+    if (target.directory !== directory) throw new OpenChamberControlError('Scheduled target moved', 409);
+  };
+
+  return {
+    validateTarget, run, beforeSend,
+    result: ({ projectId, taskId }, status, error) => record(projectId, taskId, status, error),
+    cancel: (projectId, taskId) => messageQueueRuntime.cancelScheduledTask(projectId, taskId),
+  };
+};