@ran-sh/dsh-crew 1.4.0 → 1.5.1

package/src/model-schedule.mjs

@@ -0,0 +1,207 @@
+// Per-model peak/off-peak scheduling.
+//
+// Some providers price by time of day: DeepSeek charges double during its peak
+// hours (UTC 01:00-04:00 and 06:00-10:00, Monday to Friday) and half that
+// off-peak. An operator who wants to avoid that spend needs to say which models
+// may run during peak, which must not, and which should merely be flagged.
+//
+// One schedule is shared; the per-model list decides who it applies to. A model
+// absent from the list is unrestricted — the feature is opt-in per model, so
+// turning it on never silently changes routing for everything at once.
+//
+// Wall-clock windows are stored in the configured offset, not UTC, so the value
+// an operator types is the value they see. The defaults are DeepSeek's published
+// peak hours (UTC 01:00-04:00 and 06:00-10:00, Mon-Fri) expressed in the default
+// UTC+8: 09:00-12:00 and 14:00-18:00.
+//
+// This module is pure: no I/O, no ambient clock. Callers pass `at`.
+
+/** Per-model restriction strength. Absent from the list means `off`. */
+export const MODEL_SCHEDULE_MODES = Object.freeze(['off', 'warn', 'block']);
+
+/** Peak means "expensive". Off-peak is every hour outside the windows. */
+export const DEFAULT_PEAK_WINDOWS = Object.freeze([
+  Object.freeze({ start: '09:00', end: '12:00' }),
+  Object.freeze({ start: '14:00', end: '18:00' }),
+]);
+
+export const DEFAULT_TIMEZONE_OFFSET_MINUTES = 8 * 60;
+export const DEFAULT_PEAK_WEEKDAYS = Object.freeze([1, 2, 3, 4, 5]);
+export const MINUTES_PER_DAY = 24 * 60;
+// A fixed offset is bounded by the real-world range of UTC offsets; anything
+// wider is a typo, not a timezone.
+const MAX_OFFSET_MINUTES = 14 * 60;
+
+/** "HH:MM" in 24-hour form to minutes past local midnight, or null. */
+function clockMinutes(value) {
+  if (typeof value !== 'string') return null;
+  const match = /^(\d{1,2}):(\d{2})$/.exec(value.trim());
+  if (!match) return null;
+  const hours = Number(match[1]);
+  const minutes = Number(match[2]);
+  if (!Number.isInteger(hours) || !Number.isInteger(minutes)) return null;
+  if (hours > 23 || minutes > 59) return null;
+  return hours * 60 + minutes;
+}
+
+function offsetMinutes(value, fallback) {
+  if (value === undefined || value === null) return fallback;
+  // Strict: a partially numeric string ("480garbage") or a float is a broken
+  // value, not a request for 480, and must not silently move the clock.
+  if (typeof value === 'number' ? !Number.isInteger(value) : !/^-?\d+$/.test(String(value).trim())) return null;
+  const parsed = typeof value === 'number' ? value : Number.parseInt(String(value).trim(), 10);
+  if (Math.abs(parsed) > MAX_OFFSET_MINUTES) return null;
+  return parsed;
+}
+
+function weekdayList(value, fallback) {
+  if (value === undefined || value === null) return [...fallback];
+  // A present-but-unusable container is not a request for Mon-Fri: treating it
+  // as one could switch on restrictions the operator never specified.
+  if (!Array.isArray(value)) return null;
+  return [...new Set(value.filter((day) => Number.isInteger(day) && day >= 0 && day <= 6))].sort((a, b) => a - b);
+}
+
+function peakWindows(value, fallback) {
+  if (value === undefined || value === null) return fallback.map((window) => ({ ...window }));
+  if (!Array.isArray(value)) return null;
+  const windows = [];
+  for (const entry of value) {
+    const start = clockMinutes(entry?.start);
+    const end = clockMinutes(entry?.end);
+    // A window that does not parse is dropped rather than widened to all day.
+    if (start === null || end === null || start === end) continue;
+    windows.push({ start: entry.start.trim(), end: entry.end.trim() });
+  }
+  return windows;
+}
+
+function modelModes(value) {
+  if (!Array.isArray(value)) return [];
+  const seen = new Set();
+  const modes = [];
+  for (const entry of value) {
+    const provider = typeof entry?.provider === 'string' ? entry.provider.trim() : '';
+    const model = typeof entry?.model === 'string' ? entry.model.trim() : '';
+    const mode = typeof entry?.mode === 'string' ? entry.mode.trim() : '';
+    if (!provider || !model || !MODEL_SCHEDULE_MODES.includes(mode)) continue;
+    // `off` is the absence of a rule, so it is not stored.
+    if (mode === 'off') continue;
+    const key = `${provider}\0${model}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    modes.push({ provider, model, mode });
+  }
+  return modes;
+}
+
+/**
+ * Coerce a stored or user-supplied schedule into the canonical shape.
+ *
+ * Lenient toward *missing* fields, strict toward *broken* ones. A missing field
+ * gets its documented default; a field that is present but unusable (a string
+ * where a list belongs, a non-integer offset) makes the whole schedule
+ * non-restricting instead of substituting defaults. Substituting would let
+ * accidental corruption switch on restrictions the operator never asked for.
+ */
+export function normalizeModelSchedule(raw) {
+  const source = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+  // Keep the per-model rules even when the schedule turns inert: with no windows
+  // nothing is ever peak, so the rules cannot fire, and preserving them means a
+  // corrupted window does not also destroy the operator's model choices once the
+  // coerced config is written back.
+  const models = modelModes(source.models);
+  const offset = offsetMinutes(source.timezone_offset_minutes, DEFAULT_TIMEZONE_OFFSET_MINUTES);
+  const weekdays = weekdayList(source.weekdays, DEFAULT_PEAK_WEEKDAYS);
+  const windows = peakWindows(source.peak_windows, DEFAULT_PEAK_WINDOWS);
+  if (offset === null || weekdays === null || windows === null) {
+    // Fail open by emptying the axis that activates restrictions — weekdays
+    // schedule the windows — while keeping every field that still parses. A
+    // whole-schedule reset would discard a valid custom offset and windows, and
+    // the panel writes the schedule as a whole, so that loss could stick.
+    return {
+      timezone_offset_minutes: offset === null ? DEFAULT_TIMEZONE_OFFSET_MINUTES : offset,
+      weekdays: [],
+      peak_windows: windows === null ? [] : windows,
+      models,
+    };
+  }
+  return {
+    timezone_offset_minutes: offset,
+    weekdays,
+    peak_windows: windows,
+    models,
+  };
+}
+
+export function defaultModelSchedule() {
+  return normalizeModelSchedule({
+    timezone_offset_minutes: DEFAULT_TIMEZONE_OFFSET_MINUTES,
+    weekdays: [...DEFAULT_PEAK_WEEKDAYS],
+    peak_windows: DEFAULT_PEAK_WINDOWS.map((window) => ({ ...window })),
+    models: [],
+  });
+}
+
+/** Local wall clock for an instant under a fixed offset. */
+function localParts(at, offset) {
+  const shifted = new Date(at.getTime() + offset * 60_000);
+  return {
+    weekday: shifted.getUTCDay(),
+    minutes: shifted.getUTCHours() * 60 + shifted.getUTCMinutes(),
+  };
+}
+
+function inWindow(minutes, start, end) {
+  return start < end
+    ? minutes >= start && minutes < end
+    // A window crossing midnight runs from `start` on one day to `end` the next.
+    : minutes >= start || minutes < end;
+}
+
+/**
+ * Whether one instant falls in a peak window.
+ *
+ * A window crossing midnight also belongs to the weekday it starts on, so the
+ * early-morning half is checked against the previous day.
+ */
+export function isPeakAt(schedule, at = new Date()) {
+  const normalized = normalizeModelSchedule(schedule);
+  if (normalized.weekdays.length === 0) return false;
+  const { weekday, minutes } = localParts(at, normalized.timezone_offset_minutes);
+  for (const window of normalized.peak_windows) {
+    const start = clockMinutes(window.start);
+    const end = clockMinutes(window.end);
+    if (start === null || end === null) continue;
+    if (!inWindow(minutes, start, end)) continue;
+    const owner = start < end || minutes >= start ? weekday : (weekday + 6) % 7;
+    if (normalized.weekdays.includes(owner)) return true;
+  }
+  return false;
+}
+
+/** The configured mode for one model ref; an unlisted model is unrestricted. */
+export function modelScheduleMode(schedule, ref) {
+  const provider = typeof ref?.provider === 'string' ? ref.provider.trim() : '';
+  const model = typeof ref?.model === 'string' ? ref.model.trim() : '';
+  if (!provider || !model) return 'off';
+  const entry = normalizeModelSchedule(schedule).models.find(
+    (candidate) => candidate.provider === provider && candidate.model === model,
+  );
+  return entry?.mode ?? 'off';
+}
+
+/**
+ * Decide whether one model ref is currently peak-restricted.
+ *
+ * Returns `null` when the model is unrestricted, off-peak, or the schedule is
+ * empty; otherwise `{ mode, peak: true }` where `mode` is `warn` or `block`.
+ * The caller decides: `block` skips the candidate, `warn` selects it and records
+ * the advisory.
+ */
+export function scheduleAdmission(schedule, ref, at = new Date()) {
+  const mode = modelScheduleMode(schedule, ref);
+  if (mode === 'off') return null;
+  if (!isPeakAt(schedule, at)) return null;
+  return { mode, peak: true };
+}

package/src/policy.mjs

@@ -9,23 +9,24 @@
 export * from './policy-legacy.mjs';
 import * as legacy from './policy-legacy.mjs';
 import { normalizeAdaptiveRouting } from './adaptive-routing.mjs';
+import { normalizeModelSchedule } from './model-schedule.mjs';
 
-export { normalizeAdaptiveRouting };
-export const CONFIG_SCHEMA_VERSION = 4;
-const MIN_CANONICAL_SCHEMA_VERSION = 3;
-
-function validObject(value) {
-  return !!value && typeof value === 'object' && !Array.isArray(value);
-}
-
-const EXECUTION_TRANSPORTS = new Set(['hub-3210', 'standalone-legacy']);
-
-function normalizeExecutionTransport(value) {
-  return EXECUTION_TRANSPORTS.has(value) ? value : 'hub-3210';
-}
-
-function hasCanonicalAuthority(raw) {
-  return Number(raw?.config_schema_version) >= MIN_CANONICAL_SCHEMA_VERSION
+export { normalizeAdaptiveRouting };
+export const CONFIG_SCHEMA_VERSION = 4;
+const MIN_CANONICAL_SCHEMA_VERSION = 3;
+
+function validObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+const EXECUTION_TRANSPORTS = new Set(['hub-3210', 'standalone-legacy']);
+
+function normalizeExecutionTransport(value) {
+  return EXECUTION_TRANSPORTS.has(value) ? value : 'hub-3210';
+}
+
+function hasCanonicalAuthority(raw) {
+  return Number(raw?.config_schema_version) >= MIN_CANONICAL_SCHEMA_VERSION
     && validObject(raw?.worker)
     && validObject(raw?.review)
     && validObject(raw?.execution);
@@ -71,44 +72,49 @@ function normalizeLegacySnapshot(raw, canonical) {
   };
 }
 
-function modelPolicyWithAdaptive(basePolicy, rawPolicy) {
-  const adaptive = normalizeAdaptiveRouting(rawPolicy?.adaptive);
-  const ordering = rawPolicy?.ordering === 'health-aware' || rawPolicy?.ordering === 'manual'
-    ? rawPolicy.ordering
-    : adaptive.enabled ? 'health-aware' : 'manual';
-  return {
-    ...basePolicy,
-    adaptive: { ...adaptive, enabled: ordering === 'health-aware' },
-    ordering,
-    health_gate: rawPolicy?.health_gate === 'off' ? 'off' : 'hard-failures',
-  };
-}
+function modelPolicyWithAdaptive(basePolicy, rawPolicy) {
+  const adaptive = normalizeAdaptiveRouting(rawPolicy?.adaptive);
+  const ordering = rawPolicy?.ordering === 'health-aware' || rawPolicy?.ordering === 'manual'
+    ? rawPolicy.ordering
+    : adaptive.enabled ? 'health-aware' : 'manual';
+  return {
+    ...basePolicy,
+    adaptive: { ...adaptive, enabled: ordering === 'health-aware' },
+    ordering,
+    health_gate: rawPolicy?.health_gate === 'off' ? 'off' : 'hard-failures',
+  };
+}
 
 function normalizeCanonical(raw) {
   const base = legacy.getCanonical(raw);
   const providerMode = legacy.normalizeWorkerProviderMode(base.worker?.provider_mode);
   const canonical = {
     ...base,
-    execution: {
-      ...base.execution,
+    execution: {
+      ...base.execution,
       // There is one global dispatch permission. `execution.enabled` is a
       // canonical mirror of the top-level switch, never a second authority.
-      enabled: base.subagents_enabled,
-      transport: normalizeExecutionTransport(raw?.execution?.transport ?? base.execution?.transport),
-    },
+      enabled: base.subagents_enabled,
+      transport: normalizeExecutionTransport(raw?.execution?.transport ?? base.execution?.transport),
+    },
     worker: {
       ...base.worker,
       provider_mode: providerMode,
       model_policy: modelPolicyWithAdaptive(base.worker.model_policy, raw?.worker?.model_policy),
     },
-    review: {
-      ...base.review,
-      gate: ['required', 'optional', 'off'].includes(raw?.review?.gate) ? raw.review.gate : 'required',
+    review: {
+      ...base.review,
+      gate: ['required', 'optional', 'off'].includes(raw?.review?.gate) ? raw.review.gate : 'required',
       // v0.3 still exposes one Worker Provider selector. Until per-role
       // provider modes become first-class, keep both roles aligned.
       provider_mode: providerMode,
       model_policy: modelPolicyWithAdaptive(base.review.model_policy, raw?.review?.model_policy),
     },
+    // One schedule regulates every restricted model; the per-model list decides
+    // who it applies to. Top-level rather than per-role because the same model
+    // can sit in either role's priority list, so the restriction is a property
+    // of the model, not of the role that happens to route to it.
+    model_schedule: normalizeModelSchedule(raw?.model_schedule),
   };
   canonical.legacy = normalizeLegacySnapshot(raw, canonical);
   return canonical;
@@ -170,6 +176,7 @@ export function normalizeGlobalConfig(raw = {}) {
     review_state: canonical.review.state,
     auto_review: canonical.review.auto_review === true,
     worker_provider_mode: canonical.worker.provider_mode,
+    model_schedule: canonical.model_schedule,
     flash_model_priority: [...canonical.worker.model_policy.priority],
     flash_model_priority_configured: canonical.worker.model_policy.priorityConfigured,
     flash_model_fallback: canonical.worker.model_policy.fallback,
@@ -191,32 +198,32 @@ export function normalizeGlobalConfig(raw = {}) {
  * adaptive sub-domain, so direct canonical-ish v0.2 callers retain the exact
  * priority/escalation semantics they had before schema-v3 existed.
  */
-export function resolveModelPolicy(config = {}, role = 'worker', context = {}) {
-  const base = legacy.resolveModelPolicy(config, role, context);
-  const rawPolicy = role === 'reviewer'
-    ? config?.review?.model_policy
-    : config?.worker?.model_policy;
-  const adaptive = normalizeAdaptiveRouting(rawPolicy?.adaptive ?? base.adaptive);
-  const ordering = rawPolicy?.ordering === 'health-aware' || rawPolicy?.ordering === 'manual'
-    ? rawPolicy.ordering
-    : adaptive.enabled ? 'health-aware' : 'manual';
-  return {
-    ...base,
-    adaptive: { ...adaptive, enabled: ordering === 'health-aware' },
-    ordering,
-    health_gate: rawPolicy?.health_gate === 'off' ? 'off' : 'hard-failures',
-  };
-}
-
-/** Automatic review respects the v4 reviewer gate; session opt-out remains authoritative. */
-export function shouldAutoReview(config = {}, session = {}) {
-  const normalized = normalizeGlobalConfig(config);
-  const gate = ['required', 'optional', 'off'].includes(config?.review?.gate)
-    ? config.review.gate
-    : normalized.review?.gate;
-  if (gate === 'off') return false;
-  return legacy.shouldAutoReview(normalized, session);
-}
+export function resolveModelPolicy(config = {}, role = 'worker', context = {}) {
+  const base = legacy.resolveModelPolicy(config, role, context);
+  const rawPolicy = role === 'reviewer'
+    ? config?.review?.model_policy
+    : config?.worker?.model_policy;
+  const adaptive = normalizeAdaptiveRouting(rawPolicy?.adaptive ?? base.adaptive);
+  const ordering = rawPolicy?.ordering === 'health-aware' || rawPolicy?.ordering === 'manual'
+    ? rawPolicy.ordering
+    : adaptive.enabled ? 'health-aware' : 'manual';
+  return {
+    ...base,
+    adaptive: { ...adaptive, enabled: ordering === 'health-aware' },
+    ordering,
+    health_gate: rawPolicy?.health_gate === 'off' ? 'off' : 'hard-failures',
+  };
+}
+
+/** Automatic review respects the v4 reviewer gate; session opt-out remains authoritative. */
+export function shouldAutoReview(config = {}, session = {}) {
+  const normalized = normalizeGlobalConfig(config);
+  const gate = ['required', 'optional', 'off'].includes(config?.review?.gate)
+    ? config.review.gate
+    : normalized.review?.gate;
+  if (gate === 'off') return false;
+  return legacy.shouldAutoReview(normalized, session);
+}
 
 /** Explicit legacy-import normalizer for the persistence layer. */
 export function normalizeLegacyGlobalConfig(raw = {}) {

package/src/release-in-use.mjs

@@ -0,0 +1,110 @@
+// Release liveness claims.
+//
+// A running Hub keeps executing the release it was started from, but it loads
+// several modules lazily with a cache-busting query (`import('...?t=' + Date.now())`)
+// so that a config edit is visible without a restart. Those lazy reads go to
+// disk every time, which means deleting the release under a live process breaks
+// it permanently: the routes that were already loaded keep working while
+// everything behind a lazy import answers 500.
+//
+// Release retention keeps only the newest few, and it protected the *current*
+// pointer — not the one a running process is actually executing. So a machine
+// could be left with a Hub whose config routes were dead, and an update would
+// not repair it because the damage is to the process, not the files.
+//
+// A process therefore records that it is using a release. Retention skips any
+// release with a live claim. Liveness is decided by the pid, not by the file, so
+// a process that dies without cleaning up cannot pin a release forever.
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const IN_USE_DIRNAME = 'in-use';
+
+export function releaseInUseDir({ home = homedir() } = {}) {
+  return join(home, '.config', 'dsh-crew', 'app', IN_USE_DIRNAME);
+}
+
+/** The release root that owns `moduleUrl`, or null when it is outside one. */
+export function releaseRootFor(moduleUrl) {
+  let path;
+  try { path = fileURLToPath(moduleUrl); } catch { return null; }
+  // <release>/src/<...> or <release>/src/hub/entry.mjs → walk up to the release root.
+  let dir = dirname(path);
+  for (let depth = 0; depth < 6; depth++) {
+    if (existsSync(join(dir, 'package.json'))) {
+      try {
+        const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+        if (pkg?.name === '@ran-sh/dsh-crew') return resolve(dir);
+      } catch { /* not the payload manifest; keep walking */ }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function isAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error?.code === 'EPERM'; }
+}
+
+/**
+ * Record that this process is running `releasePath`. Best effort: failing to
+ * claim must never stop the Hub from starting, because the cost of a missed
+ * claim is a possible retention of one extra release.
+ */
+export function claimReleaseInUse({ moduleUrl = import.meta.url, releasePath, home = homedir(), pid = process.pid, now = Date.now() } = {}) {
+  try {
+    const target = releasePath ?? releaseRootFor(moduleUrl);
+    if (!target) return null;
+    const dir = releaseInUseDir({ home });
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, `${pid}.json`);
+    writeFileSync(file, JSON.stringify({ pid, release: resolve(target), claimed_at: now }) + '\n');
+    return file;
+  } catch { return null; }
+}
+
+export function releaseClaimFile({ home = homedir(), pid = process.pid } = {}) {
+  return join(releaseInUseDir({ home }), `${pid}.json`);
+}
+
+export function releaseClaimInUse({ home = homedir(), pid = process.pid } = {}) {
+  const file = releaseClaimFile({ home, pid });
+  return existsSync(file) || false;
+}
+
+export function clearReleaseClaim({ home = homedir(), pid = process.pid } = {}) {
+  try { rmSync(releaseClaimFile({ home, pid }), { force: true }); return true; } catch { return false; }
+}
+
+/**
+ * Releases currently held by a live process. Dead claims are removed as they are
+ * encountered, so the directory cannot accumulate stale files.
+ */
+export function liveReleaseClaims({ home = homedir(), alive = isAlive } = {}) {
+  const dir = releaseInUseDir({ home });
+  let names;
+  // A state directory that is unreadable — or replaced by a file — must read as
+  // "no claims" rather than throwing: this runs inside install, and failing it
+  // would block an update over a problem that only affects pruning.
+  try { names = readdirSync(dir); } catch { return []; }
+  const live = [];
+  for (const name of names) {
+    if (!name.endsWith('.json')) continue;
+    const file = join(dir, name);
+    let record;
+    try { record = JSON.parse(readFileSync(file, 'utf8')); } catch { record = null; }
+    if (record && Number.isInteger(record.pid) && typeof record.release === 'string' && alive(record.pid)) {
+      live.push(resolve(record.release));
+      continue;
+    }
+    try { rmSync(file, { force: true }); } catch { /* best effort */ }
+  }
+  return [...new Set(live)];
+}

package/src/runtime-identity.mjs

@@ -36,7 +36,7 @@ export {
 // included in the identity contract.
 const RUNTIME_ID = randomUUID();
 
-export const RUNTIME_VERSION = '1.4.0';
+export const RUNTIME_VERSION = '1.5.1';
 export const HUB_PROTOCOL_VERSION = 1;
 
 export const HUB_CAPABILITIES = Object.freeze([

package/src/server.mjs

@@ -421,7 +421,12 @@ async function buildConfigReport() {
             reason_code: workspaceReadiness.reason_code ?? workspaceReadiness.code ?? 'WORKSPACE_NOT_CHECKED',
           },
         };
-        const modelCallability = reprojectRuntimeModelCallability(snapshot, { enabled_roles });
+        // `reprojectRuntimeModelCallability` takes `enabled_roles`; the local
+        // binding is camelCase. Naming the property matters: a bare
+        // `{ enabled_roles }` shorthand is a ReferenceError, and it fires on
+        // every report whenever the Hub returns a readiness snapshot, which is
+        // the normal case.
+        const modelCallability = reprojectRuntimeModelCallability(snapshot, { enabled_roles: enabledRoles });
         return modelCallability ? { ...snapshot, model_callability: modelCallability } : snapshot;
       })()
     : buildRuntimeReadinessSnapshot({