@matteeh/osq 0.1.0 → 0.2.0

package/dist/core/foundation/config-queue.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Queue planning ceilings. Both values are required together when the block is
+ * present; no default session or monetary limit is invented.
+ */
+export interface QueueConfig {
+    readonly maxPlanningSessions: number;
+    readonly maxPlanningCost: number;
+}
+/**
+ * Validate an optional `queue` block. When present it is atomic: both ceilings
+ * must be finite non-negative numbers. Absence stays valid so repositories that
+ * never run a non-print next-item plan need no queue settings.
+ */
+export declare function validateQueueConfig(queue: unknown): QueueConfig;
+//# sourceMappingURL=config-queue.d.ts.map

package/dist/core/foundation/config-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-queue.d.ts","sourceRoot":"","sources":["../../../src/core/foundation/config-queue.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAiB/D"}

package/dist/core/foundation/config-queue.js

@@ -0,0 +1,24 @@
+/**
+ * Validate an optional `queue` block. When present it is atomic: both ceilings
+ * must be finite non-negative numbers. Absence stays valid so repositories that
+ * never run a non-print next-item plan need no queue settings.
+ */
+export function validateQueueConfig(queue) {
+    if (typeof queue !== 'object' || queue === null || Array.isArray(queue)) {
+        throw new Error('queue configuration must be an object with the two planning ceilings');
+    }
+    const record = queue;
+    if (record.maxPlanningSessions === undefined || record.maxPlanningCost === undefined) {
+        throw new Error('queue.maxPlanningSessions and queue.maxPlanningCost are both required');
+    }
+    const sessions = record.maxPlanningSessions;
+    const cost = record.maxPlanningCost;
+    if (typeof sessions !== 'number' || !Number.isFinite(sessions) || sessions < 0) {
+        throw new Error('queue.maxPlanningSessions must be a finite non-negative number');
+    }
+    if (typeof cost !== 'number' || !Number.isFinite(cost) || cost < 0) {
+        throw new Error('queue.maxPlanningCost must be a finite non-negative number');
+    }
+    return { maxPlanningSessions: sessions, maxPlanningCost: cost };
+}
+//# sourceMappingURL=config-queue.js.map

package/dist/core/foundation/config-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-queue.js","sourceRoot":"","sources":["../../../src/core/foundation/config-queue.ts"],"names":[],"mappings":"AASA;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxE,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAC;IAC1F,CAAC;IACD,MAAM,MAAM,GAAG,KAAgC,CAAC;IAChD,IAAI,MAAM,CAAC,mBAAmB,KAAK,SAAS,IAAI,MAAM,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;QACrF,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;IAC3F,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,CAAC,mBAAmB,CAAC;IAC5C,MAAM,IAAI,GAAG,MAAM,CAAC,eAAe,CAAC;IACpC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QAC/E,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAC;IACpF,CAAC;IACD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;QACnE,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IAChF,CAAC;IACD,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC;AAClE,CAAC"}

package/dist/core/foundation/config-serve.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Read-only dashboard server settings. Both values are validated and defaulted
+ * here so `defineConfig` owns the merged public configuration.
+ */
+export interface ServeConfig {
+    /** Loopback port; `0` requests an operating-system-assigned port. */
+    readonly port: number;
+    /** Debounce window for filesystem invalidation notifications. */
+    readonly eventDebounceMs: number;
+}
+export declare const DEFAULT_SERVE_CONFIG: ServeConfig;
+/** A valid selected port is an integer from 0 through 65535 inclusive. */
+export declare function isValidPort(value: number): boolean;
+/**
+ * Validate an optional `serve` block over the defaults. A partial block keeps
+ * the missing value's default; non-finite, fractional, negative, or
+ * out-of-range ports and non-finite or negative debounce values are rejected.
+ */
+export declare function validateServeConfig(serve: unknown): ServeConfig;
+//# sourceMappingURL=config-serve.d.ts.map

package/dist/core/foundation/config-serve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-serve.d.ts","sourceRoot":"","sources":["../../../src/core/foundation/config-serve.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,eAAO,MAAM,oBAAoB,EAAE,WAGlC,CAAC;AAEF,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAsB/D"}

package/dist/core/foundation/config-serve.js

@@ -0,0 +1,35 @@
+export const DEFAULT_SERVE_CONFIG = {
+    port: 4173,
+    eventDebounceMs: 100,
+};
+/** A valid selected port is an integer from 0 through 65535 inclusive. */
+export function isValidPort(value) {
+    return Number.isInteger(value) && value >= 0 && value <= 65535;
+}
+/**
+ * Validate an optional `serve` block over the defaults. A partial block keeps
+ * the missing value's default; non-finite, fractional, negative, or
+ * out-of-range ports and non-finite or negative debounce values are rejected.
+ */
+export function validateServeConfig(serve) {
+    if (serve === undefined)
+        return DEFAULT_SERVE_CONFIG;
+    if (typeof serve !== 'object' || serve === null || Array.isArray(serve)) {
+        throw new Error('serve configuration must be an object with port and eventDebounceMs');
+    }
+    const record = serve;
+    const port = record.port === undefined ? DEFAULT_SERVE_CONFIG.port : record.port;
+    const eventDebounceMs = record.eventDebounceMs === undefined
+        ? DEFAULT_SERVE_CONFIG.eventDebounceMs
+        : record.eventDebounceMs;
+    if (typeof port !== 'number' || !isValidPort(port)) {
+        throw new Error('serve.port must be an integer from 0 through 65535');
+    }
+    if (typeof eventDebounceMs !== 'number' ||
+        !Number.isFinite(eventDebounceMs) ||
+        eventDebounceMs < 0) {
+        throw new Error('serve.eventDebounceMs must be a finite non-negative number');
+    }
+    return { port, eventDebounceMs };
+}
+//# sourceMappingURL=config-serve.js.map

package/dist/core/foundation/config-serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-serve.js","sourceRoot":"","sources":["../../../src/core/foundation/config-serve.ts"],"names":[],"mappings":"AAWA,MAAM,CAAC,MAAM,oBAAoB,GAAgB;IAC/C,IAAI,EAAE,IAAI;IACV,eAAe,EAAE,GAAG;CACrB,CAAC;AAEF,0EAA0E;AAC1E,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,KAAK,IAAI,KAAK,CAAC;AACjE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,oBAAoB,CAAC;IACrD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxE,MAAM,IAAI,KAAK,CAAC,qEAAqE,CAAC,CAAC;IACzF,CAAC;IACD,MAAM,MAAM,GAAG,KAAgC,CAAC;IAChD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC;IACjF,MAAM,eAAe,GACnB,MAAM,CAAC,eAAe,KAAK,SAAS;QAClC,CAAC,CAAC,oBAAoB,CAAC,eAAe;QACtC,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC;IAC7B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACxE,CAAC;IACD,IACE,OAAO,eAAe,KAAK,QAAQ;QACnC,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAC;QACjC,eAAe,GAAG,CAAC,EACnB,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IAChF,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC;AACnC,CAAC"}

package/dist/core/{config.d.ts → foundation/config.d.ts}

@@ -1,3 +1,13 @@
+import { type CodexConfig } from './config-codex.js';
+import { type GatesConfig } from './config-gates.js';
+import { type PiConfig } from './config-pi.js';
+import { type PlanningConfig } from './config-planning.js';
+import { type QueueConfig } from './config-queue.js';
+import { type ServeConfig } from './config-serve.js';
+export type { CodexConfig } from './config-codex.js';
+export type { PiConfig } from './config-pi.js';
+export type { QueueConfig } from './config-queue.js';
+export type { ServeConfig } from './config-serve.js';
 export interface OsqLimits {
     readonly maxScopeFiles: number;
     readonly maxFeatureWrites: number;
@@ -5,16 +15,19 @@ export interface OsqLimits {
     readonly maxAcceptanceLines: number;
 }
 export interface OsqPaths {
-    readonly specs: string;
-    readonly archive: string;
     readonly features: string;
     readonly decisions: string;
     readonly templates: string;
+    readonly openspecRoot: string;
 }
 export interface OsqTimeouts {
     readonly staleLockSeconds: number;
     readonly taskTimeoutSeconds: number;
     readonly verifyTimeoutSeconds: number;
+    /** Preflight `--version` probe deadline; defaults to 10 seconds. */
+    readonly harnessPreflightSeconds?: number;
+    /** Kill grace after SIGTERM before SIGKILL; defaults to 5000 milliseconds. */
+    readonly harnessKillGracePeriodMs?: number;
 }
 export interface AgyConfig {
     readonly model?: string;
@@ -29,6 +42,11 @@ export interface OpencodeConfig {
 export interface LogConfig {
     readonly heartbeatSeconds?: number;
 }
+export interface PlannerConfig {
+    readonly harness: string;
+    readonly model: string;
+    readonly agent?: string;
+}
 export interface OsqConfig {
     readonly harness: string;
     readonly maxConcurrency: number;
@@ -37,15 +55,28 @@ export interface OsqConfig {
     readonly timeouts: OsqTimeouts;
     readonly agy?: AgyConfig;
     readonly opencode?: OpencodeConfig;
+    readonly codex?: CodexConfig;
+    readonly pi?: PiConfig;
     readonly log?: LogConfig;
+    readonly planner?: PlannerConfig;
+    readonly planning?: PlanningConfig;
+    readonly queue?: QueueConfig;
+    readonly serve?: Partial<ServeConfig>;
+    readonly gates?: GatesConfig;
 }
-export type OsqUserConfig = Partial<Omit<OsqConfig, 'limits' | 'paths' | 'timeouts' | 'agy' | 'opencode' | 'log'>> & {
+export type OsqUserConfig = Partial<Omit<OsqConfig, 'limits' | 'paths' | 'timeouts' | 'codex' | 'pi' | 'log' | 'planner' | 'planning' | 'queue' | 'gates'>> & {
     readonly limits?: Partial<OsqLimits>;
     readonly paths?: Partial<OsqPaths>;
     readonly timeouts?: Partial<OsqTimeouts>;
     readonly agy?: Partial<AgyConfig>;
     readonly opencode?: Partial<OpencodeConfig>;
+    readonly codex?: Partial<CodexConfig>;
+    readonly pi?: Partial<PiConfig>;
     readonly log?: Partial<LogConfig>;
+    readonly planner?: Partial<PlannerConfig>;
+    readonly planning?: Partial<PlanningConfig>;
+    readonly queue?: Partial<QueueConfig>;
+    readonly gates?: Partial<GatesConfig>;
 };
 export declare const DEFAULT_CONFIG: OsqConfig;
 export declare function defineConfig(config: OsqUserConfig): OsqConfig;

package/dist/core/foundation/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/core/foundation/config.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,WAAW,EAA8C,MAAM,mBAAmB,CAAC;AAEjG,OAAO,EAAwB,KAAK,WAAW,EAAuB,MAAM,mBAAmB,CAAC;AAChG,OAAO,EAAE,KAAK,QAAQ,EAAoB,MAAM,gBAAgB,CAAC;AACjE,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,KAAK,WAAW,EAAuB,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EAAwB,KAAK,WAAW,EAAuB,MAAM,mBAAmB,CAAC;AAEhG,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,YAAY,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,oEAAoE;IACpE,QAAQ,CAAC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAC1C,8EAA8E;IAC9E,QAAQ,CAAC,wBAAwB,CAAC,EAAE,MAAM,CAAC;CAC5C;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,0BAA0B,CAAC,EAAE,OAAO,CAAC;CAC/C;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC;IACvB,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;CAC9B;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,CACjC,IAAI,CACF,SAAS,EACP,QAAQ,GACR,OAAO,GACP,UAAU,GACV,OAAO,GACP,IAAI,GACJ,KAAK,GACL,SAAS,GACT,UAAU,GACV,OAAO,GACP,OAAO,CACV,CACF,GAAG;IACF,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IACzC,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IAClC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IACtC,QAAQ,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChC,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;CACvC,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,SAqC5B,CAAC;AAEF,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,CA8C7D;AAED,wBAAsB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAgDxE"}

package/dist/core/{config.js → foundation/config.js}

@@ -1,9 +1,19 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { createJiti } from 'jiti';
+import { validateCodexConfig, validatePlannerConfig } from './config-codex.js';
+import { applyHarnessModelEnv } from './config-env.js';
+import { DEFAULT_GATES_CONFIG, validateGatesConfig } from './config-gates.js';
+import { validatePiConfig } from './config-pi.js';
+import { DEFAULT_PLANNING_CONFIG, validatePlanningConfig, } from './config-planning.js';
+import { validateQueueConfig } from './config-queue.js';
+import { DEFAULT_SERVE_CONFIG, validateServeConfig } from './config-serve.js';
 export const DEFAULT_CONFIG = {
     harness: 'agy',
     maxConcurrency: 1,
+    serve: DEFAULT_SERVE_CONFIG,
+    gates: DEFAULT_GATES_CONFIG,
+    planning: DEFAULT_PLANNING_CONFIG,
     agy: {
         model: 'gemini-3.8-flash-high',
         dangerouslySkipPermissions: true,
@@ -23,22 +33,37 @@ export const DEFAULT_CONFIG = {
         maxAcceptanceLines: 7,
     },
     paths: {
-        specs: 'specs',
-        archive: 'specs/archive',
-        features: 'features',
+        features: 'openspec/specs',
         decisions: 'decisions',
         templates: 'templates',
+        openspecRoot: 'openspec',
     },
     timeouts: {
         staleLockSeconds: 2700,
         taskTimeoutSeconds: 1800,
         verifyTimeoutSeconds: 600,
+        harnessPreflightSeconds: 10,
+        harnessKillGracePeriodMs: 5000,
     },
 };
 export function defineConfig(config) {
+    const { planner, queue: rawQueue, ...restConfig } = config;
+    let validatedPlanner;
+    if (planner !== undefined) {
+        validatedPlanner = validatePlannerConfig(planner);
+    }
+    const queue = rawQueue === undefined ? undefined : validateQueueConfig(rawQueue);
+    const codex = validateCodexConfig(config.codex);
+    const pi = validatePiConfig(config.pi);
+    const serve = validateServeConfig(config.serve);
     return {
         ...DEFAULT_CONFIG,
-        ...config,
+        ...restConfig,
+        serve,
+        planning: validatePlanningConfig(config.planning),
+        gates: validateGatesConfig(config.gates),
+        ...(validatedPlanner ? { planner: validatedPlanner } : {}),
+        ...(queue ? { queue } : {}),
         agy: {
             ...DEFAULT_CONFIG.agy,
             ...(config.agy || {}),
@@ -47,6 +72,8 @@ export function defineConfig(config) {
             ...DEFAULT_CONFIG.opencode,
             ...(config.opencode || {}),
         },
+        codex,
+        pi,
         log: {
             ...DEFAULT_CONFIG.log,
             ...(config.log || {}),
@@ -102,23 +129,13 @@ export async function loadConfig(projectRoot) {
         }
     }
     const harness = userConfig.harness || process.env.OSQ_HARNESS || DEFAULT_CONFIG.harness;
-    const model = userConfig.agy?.model || process.env.OSQ_MODEL || DEFAULT_CONFIG.agy?.model;
-    const opencodeModel = userConfig.opencode?.model ||
-        (harness === 'opencode' && process.env.OSQ_MODEL ? process.env.OSQ_MODEL : undefined) ||
-        DEFAULT_CONFIG.opencode?.model;
+    const envModel = process.env.OSQ_MODEL?.trim();
+    const envOverrides = envModel ? applyHarnessModelEnv(userConfig, harness, envModel) : {};
     return defineConfig({
         ...userConfig,
         harness,
-        agy: {
-            ...DEFAULT_CONFIG.agy,
-            ...(userConfig.agy || {}),
-            ...(model ? { model } : {}),
-        },
-        opencode: {
-            ...DEFAULT_CONFIG.opencode,
-            ...(userConfig.opencode || {}),
-            ...(opencodeModel ? { model: opencodeModel } : {}),
-        },
+        ...envOverrides,
+        ...(userConfig.planner ? { planner: userConfig.planner } : {}),
     });
 }
 //# sourceMappingURL=config.js.map

package/dist/core/foundation/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/core/foundation/config.ts"],"names":[],"mappings":"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"}

package/dist/core/foundation/doctor-managed.d.ts

@@ -0,0 +1,13 @@
+import { type OsqConfig } from './config.js';
+export interface ManagedBlocksResult {
+    ok: boolean;
+    message: string;
+}
+/**
+ * Compare each managed file's osq block bytes with the installed canonical
+ * values, so marker presence alone never counts as healthy. When opencode is
+ * the execution or planner harness, the executor agent file `osq setup` writes
+ * is inspected too and repaired by `osq setup`, not `osq init`.
+ */
+export declare function checkManagedBlocks(projectRoot: string, config: OsqConfig): Promise<ManagedBlocksResult>;
+//# sourceMappingURL=doctor-managed.d.ts.map

package/dist/core/foundation/doctor-managed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-managed.d.ts","sourceRoot":"","sources":["../../../src/core/foundation/doctor-managed.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkB,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAS7D,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAuCD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,mBAAmB,CAAC,CAoC9B"}

package/dist/core/foundation/doctor-managed.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { DEFAULT_CONFIG } from './config.js';
+import { CLAUDE_PLAN_COMMAND_PATH, MANAGED_AGENTS_MD_BODY, MANAGED_CLAUDE_PLAN_COMMAND, MANAGED_PLANNER_BLOCK, } from './init-blocks.js';
+import { inspectManagedBlock } from './init-managed.js';
+/**
+ * Every planning entry point osq manages. Codex reads `AGENTS.md`, the human
+ * planner model reads `PLANNER.md`, and Claude Code expands the command below.
+ */
+const MANAGED_FILES = [
+    { relPath: 'AGENTS.md', canonical: MANAGED_AGENTS_MD_BODY },
+    { relPath: 'PLANNER.md', canonical: MANAGED_PLANNER_BLOCK },
+    { relPath: CLAUDE_PLAN_COMMAND_PATH, canonical: MANAGED_CLAUDE_PLAN_COMMAND },
+];
+const PROBLEM_TEXT = {
+    'missing-block': 'is missing its managed block',
+    partial: 'has a partial managed block',
+    reversed: 'has a reversed managed block',
+    duplicated: 'has duplicate managed blocks',
+    stale: 'has a stale managed block',
+};
+/** Relative path of the executor agent file `osq setup` writes for opencode. */
+const OPENCODE_AGENT_DIR = path.join('.opencode', 'agent');
+/** `osq setup` writes the agent file for either harness selection. */
+function opencodeConfigured(config) {
+    return config.harness === 'opencode' || config.planner?.harness === 'opencode';
+}
+function opencodeAgentRelPath(config) {
+    const configured = config.opencode?.agent;
+    const agent = configured ?? DEFAULT_CONFIG.opencode?.agent ?? '';
+    return path.join(OPENCODE_AGENT_DIR, `${agent}.md`);
+}
+/**
+ * Compare each managed file's osq block bytes with the installed canonical
+ * values, so marker presence alone never counts as healthy. When opencode is
+ * the execution or planner harness, the executor agent file `osq setup` writes
+ * is inspected too and repaired by `osq setup`, not `osq init`.
+ */
+export async function checkManagedBlocks(projectRoot, config) {
+    const failures = [];
+    for (const { relPath, canonical } of MANAGED_FILES) {
+        const fullPath = path.join(projectRoot, relPath);
+        let content;
+        try {
+            content = await fs.readFile(fullPath, 'utf8');
+        }
+        catch {
+            failures.push(`${relPath} is missing`);
+            continue;
+        }
+        const problem = inspectManagedBlock(content, canonical);
+        if (problem)
+            failures.push(`${relPath} ${PROBLEM_TEXT[problem]}`);
+    }
+    const setupFailures = [];
+    if (opencodeConfigured(config)) {
+        const relPath = opencodeAgentRelPath(config);
+        try {
+            const content = await fs.readFile(path.join(projectRoot, relPath), 'utf8');
+            const problem = inspectManagedBlock(content, MANAGED_AGENTS_MD_BODY);
+            if (problem)
+                setupFailures.push(`${relPath} ${PROBLEM_TEXT[problem]}`);
+        }
+        catch {
+            setupFailures.push(`${relPath} is missing`);
+        }
+    }
+    const groups = [
+        failures.length > 0 ? `${failures.join('; ')} (run osq init)` : '',
+        setupFailures.length > 0 ? `${setupFailures.join('; ')} (run osq setup)` : '',
+    ].filter((group) => group !== '');
+    if (groups.length === 0) {
+        return { ok: true, message: 'managed blocks valid' };
+    }
+    return { ok: false, message: groups.join('; ') };
+}
+//# sourceMappingURL=doctor-managed.js.map

package/dist/core/foundation/doctor-managed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-managed.js","sourceRoot":"","sources":["../../../src/core/foundation/doctor-managed.ts"],"names":[],"mappings":"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"}

package/dist/core/foundation/doctor.d.ts

@@ -0,0 +1,19 @@
+import { type OsqConfig } from './config.js';
+export interface DoctorCheckResult {
+    name: string;
+    ok: boolean;
+    message: string;
+    /** The check passed but carries a non-failing warning; printed as `[warn]`. */
+    warning?: boolean;
+}
+export interface DoctorReport {
+    ok: boolean;
+    checks: DoctorCheckResult[];
+}
+/** Injectable seam keeps the config check hermetic under test. */
+export interface DoctorDependencies {
+    loadConfig?: (projectRoot: string) => Promise<OsqConfig>;
+    probeValidator?: (projectRoot: string) => Promise<string>;
+}
+export declare function runDoctorChecks(projectRoot: string, deps?: DoctorDependencies): Promise<DoctorReport>;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/core/foundation/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/core/foundation/doctor.ts"],"names":[],"mappings":"AAYA,OAAO,EAAkB,KAAK,SAAS,EAAc,MAAM,aAAa,CAAC;AAIzE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,iBAAiB,EAAE,CAAC;CAC7B;AAED,kEAAkE;AAClE,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACzD,cAAc,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC3D;AAwLD,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,YAAY,CAAC,CAoBvB"}

package/dist/core/foundation/doctor.js

@@ -0,0 +1,187 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { isPidRunning } from '../run/lock.js';
+import { OPENSPEC_EXPECTED_VERSION, assessOpenSpecVersion, formatInRangeWarning, } from '../spec/openspec-version.js';
+import { parseFrontmatter } from '../spec/parser.js';
+import { getArchiveDir, getChangesDir } from '../status/layout.js';
+import { harnessBinary, probeVersion } from './config-doctor.js';
+import { DEFAULT_CONFIG, loadConfig } from './config.js';
+import { checkManagedBlocks } from './doctor-managed.js';
+import { findHarness } from './harness-catalog.js';
+function make(name, ok, message) {
+    return { name, ok, message };
+}
+const exists = (target) => fs.stat(target).then(() => true, () => false);
+function validConfig(config) {
+    return (typeof config.harness === 'string' &&
+        config.harness.trim() !== '' &&
+        !!config.limits &&
+        !!config.paths &&
+        typeof config.paths.openspecRoot === 'string' &&
+        !!config.timeouts &&
+        typeof config.gates?.changeVerifyAfterTask === 'boolean');
+}
+async function checkConfig(projectRoot, deps) {
+    try {
+        const config = await (deps.loadConfig ?? loadConfig)(projectRoot);
+        if (!validConfig(config)) {
+            return {
+                check: make('config', false, 'configuration is invalid or incomplete'),
+                config: DEFAULT_CONFIG,
+            };
+        }
+        return { check: make('config', true, `loaded (harness: ${config.harness})`), config };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { check: make('config', false, `failed to load: ${message}`), config: DEFAULT_CONFIG };
+    }
+}
+async function checkHarness(projectRoot, config) {
+    const bin = harnessBinary(config);
+    if (bin === null) {
+        return { check: make('harness', true, 'no external executable required'), version: '' };
+    }
+    try {
+        const timeoutSeconds = config.timeouts.harnessPreflightSeconds ?? 10;
+        const version = await probeVersion(bin, projectRoot, timeoutSeconds);
+        return { check: make('harness', true, `${bin} ${version}`.trim()), version };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            check: make('harness', false, `binary unavailable: ${bin} (${message})`),
+            version: '',
+        };
+    }
+}
+async function checkValidator(projectRoot, deps) {
+    try {
+        const local = path.join(projectRoot, 'node_modules', '.bin', 'openspec');
+        const bin = (await exists(local)) ? local : 'openspec';
+        const raw = deps.probeValidator
+            ? await deps.probeValidator(projectRoot)
+            : await probeVersion(bin, projectRoot);
+        const assessment = await assessOpenSpecVersion(raw);
+        if (assessment.status === 'pinned') {
+            return make('validator', true, `pinned ${OPENSPEC_EXPECTED_VERSION}`);
+        }
+        if (assessment.status === 'in-range' && assessment.range !== null) {
+            return {
+                name: 'validator',
+                ok: true,
+                warning: true,
+                message: formatInRangeWarning(assessment.version, assessment.range),
+            };
+        }
+        return make('validator', false, `openspec version ${assessment.version} differs from pinned ${OPENSPEC_EXPECTED_VERSION}`);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return make('validator', false, `binary unavailable: openspec (${message})`);
+    }
+}
+// PLANNER.md, AGENTS.md, and the Claude command all carry canonical osq
+// managed blocks; doctor compares bytes, not marker presence. The opencode
+// executor agent file is included when either harness selection is opencode and
+// is repaired by `osq setup`, not `osq init`.
+async function checkManaged(projectRoot, config) {
+    const result = await checkManagedBlocks(projectRoot, config);
+    return make('managed-blocks', result.ok, result.message);
+}
+async function listDirs(root) {
+    let entries = [];
+    try {
+        entries = await fs.readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => path.join(root, entry.name));
+}
+async function checkLocks(projectRoot, config) {
+    const changesDir = getChangesDir(config.paths.openspecRoot, projectRoot);
+    const orphaned = [];
+    for (const changeDir of await listDirs(changesDir)) {
+        const name = path.basename(changeDir);
+        if (name === 'archive' || name.startsWith('_') || name.startsWith('.'))
+            continue;
+        for (const lockDirName of ['running', 'locks']) {
+            const lockDir = path.join(changeDir, '.run', lockDirName);
+            for (const file of await fs.readdir(lockDir).catch(() => [])) {
+                if (!file.endsWith('.pid'))
+                    continue;
+                const lockPath = path.join(lockDir, file);
+                let pid = 0;
+                try {
+                    pid = Number(JSON.parse(await fs.readFile(lockPath, 'utf8')).pid);
+                }
+                catch { }
+                if (!isPidRunning(pid))
+                    orphaned.push(path.relative(projectRoot, lockPath));
+            }
+        }
+    }
+    return orphaned.length > 0
+        ? make('locks', false, `orphaned lock(s): ${orphaned.join(', ')}`)
+        : make('locks', true, 'no orphaned locks');
+}
+async function checkArchives(projectRoot, config) {
+    const root = getArchiveDir(config.paths.openspecRoot, projectRoot);
+    const corrupt = [];
+    for (const archiveDir of await listDirs(root)) {
+        const hasProposal = (await exists(path.join(archiveDir, 'proposal.md'))) ||
+            (await exists(path.join(archiveDir, 'spec.md')));
+        const hasTasks = (await exists(path.join(archiveDir, 'tasks'))) ||
+            (await exists(path.join(archiveDir, 'tasks.md')));
+        if (!hasProposal || !hasTasks)
+            corrupt.push(path.relative(projectRoot, archiveDir));
+    }
+    return corrupt.length > 0
+        ? make('archives', false, `invalid archive(s): ${corrupt.join(', ')}`)
+        : make('archives', true, 'all archives valid');
+}
+/** Active change done markers must be automated (`scope_hash`) or manual. */
+async function checkDoneMarkers(projectRoot, config) {
+    const changesDir = getChangesDir(config.paths.openspecRoot, projectRoot);
+    const invalid = [];
+    for (const changeDir of await listDirs(changesDir)) {
+        const name = path.basename(changeDir);
+        if (name === 'archive' || name.startsWith('_') || name.startsWith('.'))
+            continue;
+        const doneDir = path.join(changeDir, '.run', 'done');
+        for (const marker of await fs.readdir(doneDir).catch(() => [])) {
+            const markerPath = path.join(doneDir, marker);
+            const { data } = parseFrontmatter(await fs.readFile(markerPath, 'utf8').catch(() => ''));
+            const automated = typeof data.scope_hash === 'string';
+            const manual = data.manual === true && typeof data.reason === 'string';
+            if (!automated && !manual)
+                invalid.push(path.relative(projectRoot, markerPath));
+        }
+    }
+    if (invalid.length === 0)
+        return make('done-markers', true, 'all done markers verified');
+    return make('done-markers', false, `unverified done marker placed by hand: ${invalid.join(', ')}`);
+}
+export async function runDoctorChecks(projectRoot, deps = {}) {
+    const { check: configCheck, config } = await checkConfig(projectRoot, deps);
+    const harness = await checkHarness(projectRoot, config);
+    // A catalog entry may add checks for its own executable after a passing probe.
+    const diagnose = harness.check.ok ? findHarness(config.harness)?.diagnose : undefined;
+    const extra = diagnose ? await diagnose({ config, projectRoot, version: harness.version }) : [];
+    const checks = [
+        configCheck,
+        harness.check,
+        ...extra.map((diagnosis) => ({
+            ...make(diagnosis.name, diagnosis.ok, diagnosis.message),
+            ...(diagnosis.warning ? { warning: true } : {}),
+        })),
+        await checkManaged(projectRoot, config),
+        await checkLocks(projectRoot, config),
+        await checkArchives(projectRoot, config),
+        await checkDoneMarkers(projectRoot, config),
+        await checkValidator(projectRoot, deps),
+    ];
+    return { ok: checks.every((check) => check.ok), checks };
+}
+//# sourceMappingURL=doctor.js.map