zob-harness 0.1.0

package/.pi/extensions/zob-harness/src/prompt-packs.ts

@@ -0,0 +1,239 @@
+import { existsSync } from "node:fs";
+
+import { DEFAULT_RULES } from "./constants.js";
+import { validateOutputContractId } from "./output-contracts.js";
+import { sha256 } from "./utils/hashing.js";
+import { pathMatches, resolveRepoPath } from "./utils/paths.js";
+import { isRecord } from "./utils/records.js";
+
+export type PromptPackRole = "orchestrator" | "factory-selector" | "worker-implementer" | "oracle";
+
+export interface PromptPackContextPolicy {
+  contextScopeId: string;
+  maxContextTokens: number;
+  allowedSources: string[];
+  forbiddenSources: string[];
+  citationsRequired: true;
+}
+
+export interface PromptPackEventPolicy {
+  emitStatusOnStart: true;
+  emitStatusOnAttentionNeeded: true;
+  emitTodoClaimOnDone: true;
+  eventContract: "agent-event.v1";
+  todoClaimReducerRequired: true;
+  parentOwnedActions: true;
+  directTodoMutationAllowed: false;
+}
+
+export interface PromptPackDefinition {
+  schema: "zob.prompt-pack.v1";
+  roleId: PromptPackRole;
+  purposeHash: string;
+  promptRefs: string[];
+  skillRefs: string[];
+  docRefs: string[];
+  outputContract: string;
+  contextPolicy: PromptPackContextPolicy;
+  eventPolicy: PromptPackEventPolicy;
+  launchAuthorizationRequired: true;
+  oracleRequiredForCompletion: boolean;
+  bodyStored: false;
+  promptBodiesStored: false;
+  outputBodiesStored: false;
+}
+
+export interface PromptPackEvalResult {
+  roleId: PromptPackRole;
+  passed: boolean;
+  failedChecks: string[];
+  refsChecked: string[];
+  outputContract: string;
+  maxContextTokens: number;
+  bodyStored: false;
+  promptBodiesStored: false;
+  outputBodiesStored: false;
+}
+
+export interface PromptPackReport {
+  schema: "zob.prompt-pack-eval.v1";
+  status: "passed" | "failed";
+  runId: string;
+  packs: PromptPackDefinition[];
+  evals: PromptPackEvalResult[];
+  failedChecks: string[];
+  no_ship: boolean;
+  bodyStored: false;
+  promptBodiesStored: false;
+  outputBodiesStored: false;
+  generatedAt: string;
+}
+
+const BODY_LIKE_KEYS = new Set(["body", "task", "prompt", "output", "content", "message", "text", "rationale", "diff", "patch", "raw"]);
+
+function forbiddenPlaintextPaths(value: unknown, path = "root"): string[] {
+  if (!value || typeof value !== "object") return [];
+  if (Array.isArray(value)) return value.flatMap((item, index) => forbiddenPlaintextPaths(item, `${path}[${index}]`));
+  return Object.entries(value as Record<string, unknown>).flatMap(([key, child]) => [
+    ...(BODY_LIKE_KEYS.has(key) ? [`${path}.${key}`] : []),
+    ...forbiddenPlaintextPaths(child, `${path}.${key}`),
+  ]);
+}
+
+function contextPolicy(roleId: PromptPackRole, maxContextTokens: number): PromptPackContextPolicy {
+  return {
+    contextScopeId: `factory-agent-${roleId}`,
+    maxContextTokens,
+    allowedSources: ["repo-docs", "repo-prompts", "repo-skills", "project-dna-smoke"],
+    forbiddenSources: [".env", "**/.env*", "~/.ssh", "~/.aws", "raw-conversation-history", "secrets"],
+    citationsRequired: true,
+  };
+}
+
+function eventPolicy(): PromptPackEventPolicy {
+  return {
+    emitStatusOnStart: true,
+    emitStatusOnAttentionNeeded: true,
+    emitTodoClaimOnDone: true,
+    eventContract: "agent-event.v1",
+    todoClaimReducerRequired: true,
+    parentOwnedActions: true,
+    directTodoMutationAllowed: false,
+  };
+}
+
+function pack(roleId: PromptPackRole, purpose: string, promptRefs: string[], skillRefs: string[], docRefs: string[], outputContract: string, maxContextTokens: number, oracleRequiredForCompletion: boolean): PromptPackDefinition {
+  return {
+    schema: "zob.prompt-pack.v1",
+    roleId,
+    purposeHash: sha256(purpose),
+    promptRefs,
+    skillRefs,
+    docRefs,
+    outputContract,
+    contextPolicy: contextPolicy(roleId, maxContextTokens),
+    eventPolicy: eventPolicy(),
+    launchAuthorizationRequired: true,
+    oracleRequiredForCompletion,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+  };
+}
+
+export function defaultFactoryAgentPromptPacks(): PromptPackDefinition[] {
+  return [
+    pack(
+      "orchestrator",
+      "Route a launch-authorized general factory agent run through plan, coms, TODO claims, validation, and oracle gates.",
+      [".pi/prompts/adaptive-workflow.md", ".pi/prompts/autonomous-runtime.md", ".pi/prompts/factory.md"],
+      [".pi/skills/zob-harness/SKILL.md", ".pi/skills/zob-delegation-routing/SKILL.md", ".pi/skills/zob-goal-todo-tree/SKILL.md", ".pi/skills/zob-coms-v2-live/SKILL.md", ".pi/skills/zob-coms-safety/SKILL.md"],
+      ["docs/ZOB_GENERAL_FACTORY_AGENT_L4_L6_MASTER_PLAN.md", "docs/AUTONOMY_LEVELS.md", "docs/ZOB_ROOM_AND_ORCHESTRATOR_TARGET.md"],
+      "lead-plan.v1",
+      8000,
+      true,
+    ),
+    pack(
+      "factory-selector",
+      "Select an existing factory or forge a quarantined candidate under launch authorization and strict budget gates.",
+      [".pi/prompts/factory.md", ".pi/prompts/spec.md"],
+      [".pi/skills/zob-factory/SKILL.md", ".pi/skills/zob-sandbox/SKILL.md", ".pi/skills/zob-compute-profile/SKILL.md"],
+      ["docs/ZOB_SOFTWARE_FACTORY_MODE.md", "docs/AUTONOMOUS_SUPER_FACTORY_GOAL.md", "docs/HARNESS_CAPABILITY_MATRIX.md"],
+      "factory.v1",
+      6000,
+      true,
+    ),
+    pack(
+      "worker-implementer",
+      "Perform bounded in-scope implementation slices, emit status events, and return TODO claims with evidence rather than mutating parent TODO state.",
+      [".pi/prompts/implement.md", ".pi/prompts/adaptive-workflow.md"],
+      [".pi/skills/zob-harness/SKILL.md", ".pi/skills/zob-sandbox/SKILL.md", ".pi/skills/zob-coms-v2-live/SKILL.md"],
+      ["docs/OPERATING_MODEL.md", "docs/ARCHITECTURE.md", "docs/ZOB_GENERAL_FACTORY_AGENT_L4_L6_MASTER_PLAN.md"],
+      "implement.v1",
+      6000,
+      false,
+    ),
+    pack(
+      "oracle",
+      "Skeptically review claims, source freshness, no-ship state, and final release readiness for L4/L5/L6 autonomy.",
+      [".pi/prompts/autonomous-runtime.md", ".pi/prompts/spec.md"],
+      [".pi/skills/zob-oracle/SKILL.md", ".pi/skills/zob-autonomous-runtime/SKILL.md", ".pi/skills/zob-coms-safety/SKILL.md"],
+      ["docs/AUTONOMY_LEVELS.md", "docs/HARNESS_CAPABILITY_MATRIX.md", "docs/ZOB_GENERAL_FACTORY_AGENT_L4_L6_MASTER_PLAN.md"],
+      "oracle.v1",
+      7000,
+      true,
+    ),
+  ];
+}
+
+function validateRefs(repoRoot: string, refs: string[], label: string): string[] {
+  const errors: string[] = [];
+  for (const ref of refs) {
+    const resolved = resolveRepoPath(repoRoot, ref);
+    errors.push(...resolved.errors.map((error) => `${label}:${error}`));
+    if (resolved.errors.length === 0 && !existsSync(resolved.path)) errors.push(`${label}:missing:${ref}`);
+    for (const protectedPattern of DEFAULT_RULES.zeroAccessPaths) {
+      if (pathMatches(ref, protectedPattern, repoRoot, repoRoot)) errors.push(`${label}:zero_access:${protectedPattern}`);
+    }
+  }
+  return errors;
+}
+
+export function validatePromptPack(repoRoot: string, promptPack: PromptPackDefinition): PromptPackEvalResult {
+  const failedChecks: string[] = [];
+  if (promptPack.schema !== "zob.prompt-pack.v1") failedChecks.push("schema");
+  if (!promptPack.purposeHash || promptPack.purposeHash.length !== 64) failedChecks.push("purpose_hash");
+  failedChecks.push(...validateRefs(repoRoot, promptPack.promptRefs, "prompt_refs"));
+  failedChecks.push(...validateRefs(repoRoot, promptPack.skillRefs, "skill_refs"));
+  failedChecks.push(...validateRefs(repoRoot, promptPack.docRefs, "doc_refs"));
+  failedChecks.push(...validateOutputContractId(promptPack.outputContract).map((error) => `output_contract:${error}`));
+  failedChecks.push(...validateOutputContractId(promptPack.eventPolicy.eventContract).map((error) => `event_contract:${error}`));
+  if (promptPack.contextPolicy.maxContextTokens <= 0 || promptPack.contextPolicy.maxContextTokens > 8000) failedChecks.push("max_context_tokens");
+  if (promptPack.contextPolicy.citationsRequired !== true) failedChecks.push("citations_required");
+  if (promptPack.eventPolicy.todoClaimReducerRequired !== true || promptPack.eventPolicy.directTodoMutationAllowed !== false || promptPack.eventPolicy.parentOwnedActions !== true) failedChecks.push("event_policy_parent_owned");
+  if (promptPack.launchAuthorizationRequired !== true) failedChecks.push("launch_authorization_required");
+  if (promptPack.bodyStored !== false || promptPack.promptBodiesStored !== false || promptPack.outputBodiesStored !== false) failedChecks.push("body_free_flags");
+  failedChecks.push(...forbiddenPlaintextPaths(promptPack).map((path) => `body_like_key:${path}`));
+  return {
+    roleId: promptPack.roleId,
+    passed: failedChecks.length === 0,
+    failedChecks,
+    refsChecked: [...promptPack.promptRefs, ...promptPack.skillRefs, ...promptPack.docRefs],
+    outputContract: promptPack.outputContract,
+    maxContextTokens: promptPack.contextPolicy.maxContextTokens,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+  };
+}
+
+export function buildPromptPackReport(repoRoot: string, runId = "factory-agent-prompt-pack-smoke"): PromptPackReport {
+  const packs = defaultFactoryAgentPromptPacks();
+  const evals = packs.map((promptPack) => validatePromptPack(repoRoot, promptPack));
+  const failedChecks = evals.flatMap((result) => result.failedChecks.map((check) => `${result.roleId}:${check}`));
+  const report: PromptPackReport = {
+    schema: "zob.prompt-pack-eval.v1",
+    status: failedChecks.length === 0 ? "passed" : "failed",
+    runId,
+    packs,
+    evals,
+    failedChecks,
+    no_ship: failedChecks.length > 0,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+    generatedAt: new Date().toISOString(),
+  };
+  const bodyViolations = promptPackBodyFreeViolations(report);
+  if (bodyViolations.length > 0) {
+    report.status = "failed";
+    report.no_ship = true;
+    report.failedChecks.push(...bodyViolations.map((path) => `report_body_like_key:${path}`));
+  }
+  return report;
+}
+
+export function promptPackBodyFreeViolations(value: unknown): string[] {
+  if (!isRecord(value) && !Array.isArray(value)) return [];
+  return forbiddenPlaintextPaths(value);
+}

package/.pi/extensions/zob-harness/src/queue.ts

@@ -0,0 +1,386 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+
+import { evaluateStrictBudgetDispatchGate } from "./budget-policy.js";
+import { classifyChildStopCondition, evaluateBudgetPreflightDryRun } from "./chronicle.js";
+import { DEFAULT_RULES } from "./constants.js";
+import { incrementCounter, normalizeDailyTelemetryDate, stringFrom } from "./telemetry.js";
+import type { ChildStopCondition, FactoryRunBudgetInput, QueueState, QueueTickResult, ReadOnlyQueueJob, ReadOnlyQueueJobType } from "./types.js";
+import { sha256 } from "./utils/hashing.js";
+import { parseJsonFile } from "./utils/json.js";
+import { expandHome, isSafeArtifactName, pathMatches, safeFileStem } from "./utils/paths.js";
+import { isRecord } from "./utils/records.js";
+
+export const READ_ONLY_QUEUE_JOB_TYPES: ReadOnlyQueueJobType[] = ["docs_watch", "repo_audit_readonly", "todo_risk_report", "session_analysis"];
+const QUEUE_STATES: QueueState[] = ["pending", "running", "done", "failed"];
+const DISALLOWED_QUEUE_JOB_TYPE_WORDS = /(?:write|edit|fix|patch|autofix|github|browser|cloud|deploy|publish|commit)/i;
+const DISALLOWED_QUEUE_ADAPTERS = new Set(["write", "edit", "github", "browser", "cloud", "web", "deploy", "publish"]);
+const FORBIDDEN_QUEUE_JOB_BODY_KEYS = new Set(["task", "prompt", "output", "body", "content"]);
+const QUEUE_DAEMON_LEASE_MS = 30_000;
+const QUEUE_DAEMON_MAX_WORKERS = 1;
+const QUEUE_DAEMON_MAX_RETRIES = 1;
+
+export function getQueuePaths(repoRoot: string): Record<QueueState | "root" | "ledger", string> {
+  const root = join(repoRoot, ".pi", "queue");
+  return {
+    root,
+    pending: join(root, "pending"),
+    running: join(root, "running"),
+    done: join(root, "done"),
+    failed: join(root, "failed"),
+    ledger: join(root, "ledger.jsonl"),
+  };
+}
+
+export function ensureQueueDirs(repoRoot: string): Record<QueueState | "root" | "ledger", string> {
+  const paths = getQueuePaths(repoRoot);
+  for (const state of QUEUE_STATES) mkdirSync(paths[state], { recursive: true });
+  return paths;
+}
+
+function isReadOnlyQueueJob(value: unknown): value is ReadOnlyQueueJob {
+  return isRecord(value) && typeof value.id === "string" && typeof value.type === "string";
+}
+
+function queueJobPathSafeName(jobId: string): string {
+  return `${safeFileStem(jobId)}.json`;
+}
+
+function queueKillSwitchPath(repoRoot: string): string {
+  return join(getQueuePaths(repoRoot).root, "KILL_SWITCH");
+}
+
+function queueHeartbeatPath(repoRoot: string): string {
+  return join(getQueuePaths(repoRoot).root, "heartbeat.json");
+}
+
+function buildQueueLease(jobId: string | undefined, jobType: string | undefined): Record<string, unknown> {
+  const now = Date.now();
+  return {
+    schema: "zob.queue-daemon-lease.v1",
+    leaseId: sha256(`${jobId ?? "unknown"}:${jobType ?? "unknown"}:${now}`).slice(0, 24),
+    jobId,
+    jobType,
+    claimedAt: new Date(now).toISOString(),
+    heartbeatAt: new Date(now).toISOString(),
+    expiresAt: new Date(now + QUEUE_DAEMON_LEASE_MS).toISOString(),
+    leaseMs: QUEUE_DAEMON_LEASE_MS,
+    maxWorkers: QUEUE_DAEMON_MAX_WORKERS,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+  };
+}
+
+function writeQueueHeartbeat(repoRoot: string, lease: Record<string, unknown>, status: string): Record<string, unknown> {
+  const heartbeat = {
+    schema: "zob.queue-daemon-heartbeat.v1",
+    leaseId: lease.leaseId,
+    jobId: lease.jobId,
+    status,
+    heartbeatAt: new Date().toISOString(),
+    staleAfterMs: QUEUE_DAEMON_LEASE_MS,
+    killSwitchPath: ".pi/queue/KILL_SWITCH",
+    maxWorkers: QUEUE_DAEMON_MAX_WORKERS,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+  };
+  writeFileSync(queueHeartbeatPath(repoRoot), JSON.stringify(heartbeat, null, 2), "utf8");
+  return heartbeat;
+}
+
+function retryPolicyForJob(job: ReadOnlyQueueJob | undefined): Record<string, unknown> {
+  const attempts = typeof job?.attempts === "number" && Number.isFinite(job.attempts) && job.attempts >= 0 ? Math.floor(job.attempts) : 0;
+  const maxRetries = typeof job?.maxRetries === "number" && Number.isFinite(job.maxRetries) && job.maxRetries >= 0 ? Math.min(Math.floor(job.maxRetries), QUEUE_DAEMON_MAX_RETRIES) : QUEUE_DAEMON_MAX_RETRIES;
+  return {
+    schema: "zob.queue-daemon-retry-policy.v1",
+    attempts,
+    maxRetries,
+    retriesCapped: true,
+    retryAllowed: attempts < maxRetries,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+  };
+}
+
+function recoverStaleRunningJobs(repoRoot: string): number {
+  const paths = ensureQueueDirs(repoRoot);
+  let recovered = 0;
+  const now = Date.now();
+  for (const file of readdirSync(paths.running).filter((entry) => entry.endsWith(".json")).sort()) {
+    const runningPath = join(paths.running, file);
+    let record: unknown;
+    try {
+      record = parseJsonFile(runningPath);
+    } catch {
+      continue;
+    }
+    const lease = isRecord(record) && isRecord(record.lease) ? record.lease : undefined;
+    const expiresAt = typeof lease?.expiresAt === "string" ? Date.parse(lease.expiresAt) : Number.NaN;
+    if (!Number.isFinite(expiresAt) || now < expiresAt) continue;
+    const stalePayload = {
+      ...(isRecord(record) ? record : {}),
+      schema: "zob.queue-job-result.v1",
+      status: "failed",
+      stopCondition: "timeout",
+      staleLeaseRecovered: true,
+      recoveredAt: new Date(now).toISOString(),
+      budgetEnforced: false,
+      promptBodiesStored: false,
+      outputBodiesStored: false,
+    };
+    const finalPath = finalizeQueueJob(repoRoot, runningPath, "failed", stalePayload);
+    writeQueueLifecycleEvent(repoRoot, { event: "stale_recovered", jobFile: file, finalPath, stopCondition: "timeout", leaseId: lease?.leaseId });
+    recovered += 1;
+  }
+  return recovered;
+}
+
+function normalizeQueueJobPaths(job: ReadOnlyQueueJob): string[] {
+  return job.paths?.length ? job.paths : ["."];
+}
+
+function validateQueueJobPath(repoRoot: string, path: string): string[] {
+  const errors: string[] = [];
+  const resolved = resolve(repoRoot, expandHome(path));
+  const root = resolve(repoRoot);
+  if (resolved !== root && !resolved.startsWith(`${root}/`)) errors.push(`path must stay inside repo root: ${path}`);
+  for (const protectedPattern of [...DEFAULT_RULES.zeroAccessPaths, ...DEFAULT_RULES.readOnlyPaths]) {
+    if (pathMatches(path, protectedPattern, repoRoot, repoRoot)) errors.push(`protected path is not allowed in read-only queue jobs: ${protectedPattern}`);
+  }
+  return errors;
+}
+
+function findForbiddenQueueJobBodyKeys(value: unknown, prefix = "job"): string[] {
+  if (!value || typeof value !== "object") return [];
+  if (Array.isArray(value)) return value.flatMap((child, index) => findForbiddenQueueJobBodyKeys(child, `${prefix}[${index}]`));
+  return Object.entries(value as Record<string, unknown>).flatMap(([key, child]) => {
+    const path = `${prefix}.${key}`;
+    return [...(FORBIDDEN_QUEUE_JOB_BODY_KEYS.has(key) ? [path] : []), ...findForbiddenQueueJobBodyKeys(child, path)];
+  });
+}
+
+export function validateReadOnlyQueueJob(repoRoot: string, job: unknown): string[] {
+  const errors: string[] = [];
+  const forbiddenBodyKeys = findForbiddenQueueJobBodyKeys(job);
+  if (forbiddenBodyKeys.length > 0) errors.push(`queue job must not contain raw task/prompt/output/body/content fields: ${forbiddenBodyKeys.join(", ")}`);
+  if (!isReadOnlyQueueJob(job)) return errors.length > 0 ? errors : ["queue job must be an object with string id and type"];
+  if (job.schema !== undefined && job.schema !== "zob.queue-job.v1") errors.push("queue job schema must be zob.queue-job.v1");
+  if (!isSafeArtifactName(job.id)) errors.push(`queue job id must be path-safe: ${job.id}`);
+  if (!READ_ONLY_QUEUE_JOB_TYPES.includes(job.type as ReadOnlyQueueJobType)) errors.push(`unsupported read-only queue job type: ${job.type}`);
+  if (DISALLOWED_QUEUE_JOB_TYPE_WORDS.test(job.type)) errors.push(`unsafe queue job type is not allowed: ${job.type}`);
+  if (job.readOnly !== true) errors.push("queue job must declare readOnly=true");
+  if (job.adapters !== undefined && (!Array.isArray(job.adapters) || !job.adapters.every((adapter) => typeof adapter === "string"))) errors.push("queue job adapters must be strings when provided");
+  for (const adapter of job.adapters ?? []) {
+    if (DISALLOWED_QUEUE_ADAPTERS.has(adapter.toLowerCase())) errors.push(`unsafe queue adapter is not allowed: ${adapter}`);
+  }
+  if (job.paths !== undefined && (!Array.isArray(job.paths) || !job.paths.every((path) => typeof path === "string"))) errors.push("queue job paths must be strings when provided");
+  if (Array.isArray(job.paths)) for (const path of normalizeQueueJobPaths(job)) errors.push(...validateQueueJobPath(repoRoot, path));
+  if (job.attempts !== undefined && (!Number.isInteger(job.attempts) || job.attempts < 0)) errors.push("queue job attempts must be a nonnegative integer when provided");
+  if (job.maxRetries !== undefined && (!Number.isInteger(job.maxRetries) || job.maxRetries < 0 || job.maxRetries > QUEUE_DAEMON_MAX_RETRIES)) errors.push(`queue job maxRetries must be between 0 and ${QUEUE_DAEMON_MAX_RETRIES}`);
+  return errors;
+}
+
+export function writeQueueLifecycleEvent(repoRoot: string, event: Record<string, unknown>): string {
+  const paths = ensureQueueDirs(repoRoot);
+  const safeEvent = {
+    schema: "zob.queue-lifecycle-event.v1",
+    timestamp: new Date().toISOString(),
+    budgetEnforced: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+    ...event,
+  };
+  appendFileSync(paths.ledger, `${JSON.stringify(safeEvent)}\n`, "utf8");
+  return paths.ledger;
+}
+
+function readQueueJobFile(path: string): unknown {
+  return parseJsonFile(path);
+}
+
+function queueBudgetResult(job: ReadOnlyQueueJob): Record<string, unknown> {
+  const budget = job.budget;
+  return evaluateBudgetPreflightDryRun({
+    costUsd: budget?.observedCostUsd,
+    runs: budget?.observedRuns,
+    durationMs: budget?.observedDurationMs,
+    parallelChildren: budget?.observedParallelChildren,
+    caps: budget,
+    strictRequested: budget?.strictRequested,
+  });
+}
+
+function queueStrictBudgetGate(job: ReadOnlyQueueJob): Record<string, unknown> {
+  const budget = job.budget;
+  const strictBudget: FactoryRunBudgetInput = {
+    ...(budget?.maxCostUsd !== undefined ? { maxCostUsd: budget.maxCostUsd } : {}),
+    ...(budget?.maxRuns !== undefined ? { maxRuns: budget.maxRuns } : {}),
+    ...(budget?.maxDurationMs !== undefined ? { maxDurationMs: budget.maxDurationMs } : {}),
+    ...(budget?.maxParallelChildren !== undefined ? { maxParallelChildren: budget.maxParallelChildren } : {}),
+    strictRequested: budget?.strictRequested,
+    strictEnabled: budget?.strictEnabled,
+    estimatedCostUsd: budget?.estimatedCostUsd ?? budget?.observedCostUsd,
+    estimatedRuns: budget?.estimatedRuns ?? budget?.observedRuns,
+    estimatedDurationMs: budget?.estimatedDurationMs ?? budget?.observedDurationMs,
+    estimatedParallelChildren: budget?.estimatedParallelChildren ?? budget?.observedParallelChildren,
+  };
+  return evaluateStrictBudgetDispatchGate({
+    runId: job.id,
+    mode: "queue-daemon",
+    execution: "deterministic_metadata_only",
+    taskCount: 1,
+    selectedItems: 1,
+    budget: strictBudget,
+  });
+}
+
+function runReadOnlyQueueJobHandler(repoRoot: string, job: ReadOnlyQueueJob, strictBudgetGate: Record<string, unknown>): Record<string, unknown> {
+  const inspectedPaths = normalizeQueueJobPaths(job);
+  return {
+    schema: "zob.queue-job-result.v1",
+    jobId: job.id,
+    jobType: job.type,
+    status: "done",
+    readOnly: true,
+    liveChildExecution: false,
+    handlerMode: "deterministic_metadata_only",
+    plannedActions: {
+      docs_watch: "Inspect documentation drift and summarize changed docs without edits.",
+      repo_audit_readonly: "Audit repository structure and safety signals without edits.",
+      todo_risk_report: "Report TODO/FIXME risk locations without edits.",
+      session_analysis: "Summarize local telemetry/session ledgers without prompt/output bodies.",
+    }[job.type as ReadOnlyQueueJobType],
+    inspectedPaths,
+    pathHashes: inspectedPaths.map((path) => ({ path, hash: sha256(resolve(repoRoot, path)) })),
+    budget: queueBudgetResult(job),
+    strictBudgetGate,
+    stop: classifyChildStopCondition({ assistantTurnSeen: true, outputHash: sha256(`${job.id}:${job.type}:metadata`), outputCaptured: true, outputValidated: true, evidenceChecked: true }),
+    budgetEnforced: strictBudgetGate.budgetEnforced === true,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+    generatedAt: new Date().toISOString(),
+  };
+}
+
+function finalizeQueueJob(repoRoot: string, runningPath: string, state: "done" | "failed", payload: Record<string, unknown>): string {
+  const paths = ensureQueueDirs(repoRoot);
+  const finalPath = join(paths[state], basename(runningPath));
+  writeFileSync(runningPath, JSON.stringify(payload, null, 2), "utf8");
+  renameSync(runningPath, finalPath);
+  return finalPath;
+}
+
+export function runQueueDaemonTick(repoRoot: string): QueueTickResult {
+  const paths = ensureQueueDirs(repoRoot);
+  const killSwitchPresent = existsSync(queueKillSwitchPath(repoRoot));
+  if (killSwitchPresent) {
+    const killSwitch = { path: ".pi/queue/KILL_SWITCH", present: true, stopCondition: "blocked", bodyStored: false, promptBodiesStored: false, outputBodiesStored: false };
+    writeQueueLifecycleEvent(repoRoot, { event: "kill_switch_blocked", claimed: false, stopCondition: "blocked" });
+    return { schema: "zob.queue-tick-result.v1", claimed: false, status: "failed", errors: ["queue daemon kill switch present"], stopCondition: "blocked", killSwitch, maxWorkers: QUEUE_DAEMON_MAX_WORKERS, budgetEnforced: false, promptBodiesStored: false, outputBodiesStored: false };
+  }
+
+  const staleRecovered = recoverStaleRunningJobs(repoRoot);
+  const pending = readdirSync(paths.pending).filter((file) => file.endsWith(".json")).sort();
+  if (pending.length === 0) {
+    writeQueueLifecycleEvent(repoRoot, { event: "idle", claimed: false, staleRecovered });
+    return { schema: "zob.queue-tick-result.v1", claimed: false, status: "idle", errors: [], stopCondition: "none", staleRecovered, maxWorkers: QUEUE_DAEMON_MAX_WORKERS, budgetEnforced: false, promptBodiesStored: false, outputBodiesStored: false };
+  }
+
+  const pendingPath = join(paths.pending, pending[0]);
+  const runningPath = join(paths.running, pending[0]);
+  renameSync(pendingPath, runningPath);
+  writeQueueLifecycleEvent(repoRoot, { event: "claimed", jobFile: pending[0], claimedPath: runningPath, maxWorkers: QUEUE_DAEMON_MAX_WORKERS, staleRecovered });
+
+  let job: unknown;
+  try {
+    job = readQueueJobFile(runningPath);
+  } catch (error) {
+    const errors = [`could not parse queue job: ${error instanceof Error ? error.message : String(error)}`];
+    const finalPath = finalizeQueueJob(repoRoot, runningPath, "failed", { schema: "zob.queue-job-result.v1", status: "failed", errors, budgetEnforced: false, promptBodiesStored: false, outputBodiesStored: false });
+    writeQueueLifecycleEvent(repoRoot, { event: "failed", jobFile: pending[0], errors, stopCondition: "failed_preflight" });
+    return { schema: "zob.queue-tick-result.v1", claimed: true, status: "failed", claimedPath: runningPath, finalPath, errors, stopCondition: "failed_preflight", staleRecovered, maxWorkers: QUEUE_DAEMON_MAX_WORKERS, budgetEnforced: false, promptBodiesStored: false, outputBodiesStored: false };
+  }
+
+  const errors = validateReadOnlyQueueJob(repoRoot, job);
+  const jobId = isReadOnlyQueueJob(job) ? job.id : undefined;
+  const jobType = isReadOnlyQueueJob(job) ? job.type : undefined;
+  if (errors.length > 0 || !isReadOnlyQueueJob(job)) {
+    const finalPath = finalizeQueueJob(repoRoot, runningPath, "failed", { schema: "zob.queue-job-result.v1", jobId, jobType, status: "failed", errors, stopCondition: "failed_preflight", budgetEnforced: false, promptBodiesStored: false, outputBodiesStored: false });
+    writeQueueLifecycleEvent(repoRoot, { event: "failed", jobId, jobType, jobFile: pending[0], errors, stopCondition: "failed_preflight" });
+    return { schema: "zob.queue-tick-result.v1", claimed: true, jobId, jobType, status: "failed", claimedPath: runningPath, finalPath, errors, stopCondition: "failed_preflight", staleRecovered, maxWorkers: QUEUE_DAEMON_MAX_WORKERS, retryPolicy: retryPolicyForJob(isReadOnlyQueueJob(job) ? job : undefined), budgetEnforced: false, promptBodiesStored: false, outputBodiesStored: false };
+  }
+
+  const strictBudgetGate = queueStrictBudgetGate(job);
+  if (strictBudgetGate.wouldBlockDispatch === true) {
+    const finalPath = finalizeQueueJob(repoRoot, runningPath, "failed", { schema: "zob.queue-job-result.v1", jobId: job.id, jobType: job.type, status: "failed", errors: ["strict budget gate blocked queue daemon job before handler"], stopCondition: "blocked", strictBudgetGate, budgetEnforced: strictBudgetGate.budgetEnforced === true, promptBodiesStored: false, outputBodiesStored: false });
+    writeQueueLifecycleEvent(repoRoot, { event: "strict_budget_blocked", jobId: job.id, jobType: job.type, jobFile: pending[0], finalPath, stopCondition: "blocked", strictBudgetGate });
+    return { schema: "zob.queue-tick-result.v1", claimed: true, jobId: job.id, jobType: job.type, status: "failed", claimedPath: runningPath, finalPath, errors: ["strict budget gate blocked queue daemon job before handler"], stopCondition: "blocked", strictBudgetGate, staleRecovered, maxWorkers: QUEUE_DAEMON_MAX_WORKERS, retryPolicy: retryPolicyForJob(job), budgetEnforced: strictBudgetGate.budgetEnforced === true, promptBodiesStored: false, outputBodiesStored: false };
+  }
+
+  const lease = buildQueueLease(job.id, job.type);
+  const heartbeat = writeQueueHeartbeat(repoRoot, lease, "running");
+  writeFileSync(runningPath, JSON.stringify({ ...job, lease, heartbeat, scheduler: { schema: "zob.queue-daemon-scheduler.v1", maxWorkers: QUEUE_DAEMON_MAX_WORKERS, claimAtMostOneJobPerTick: true, boundedRetries: true, bodyStored: false, promptBodiesStored: false, outputBodiesStored: false } }, null, 2), "utf8");
+  writeQueueLifecycleEvent(repoRoot, { event: "heartbeat", jobId: job.id, jobType: job.type, leaseId: lease.leaseId, heartbeatAt: heartbeat.heartbeatAt });
+
+  const result: Record<string, unknown> = { ...runReadOnlyQueueJobHandler(repoRoot, job, strictBudgetGate), lease, heartbeat, retryPolicy: retryPolicyForJob(job), maxWorkers: QUEUE_DAEMON_MAX_WORKERS };
+  const stopCondition = isRecord(result.stop) && typeof result.stop.stopCondition === "string" ? (result.stop.stopCondition as ChildStopCondition) : "none";
+  const finalPath = finalizeQueueJob(repoRoot, runningPath, stopCondition === "none" ? "done" : "failed", result);
+  writeQueueLifecycleEvent(repoRoot, { event: stopCondition === "none" ? "done" : "failed", jobId: job.id, jobType: job.type, jobFile: pending[0], finalPath, stopCondition, leaseId: lease.leaseId });
+  return { schema: "zob.queue-tick-result.v1", claimed: true, jobId: job.id, jobType: job.type, status: stopCondition === "none" ? "done" : "failed", claimedPath: runningPath, finalPath, errors: [], stopCondition, lease, heartbeat, staleRecovered, maxWorkers: QUEUE_DAEMON_MAX_WORKERS, retryPolicy: retryPolicyForJob(job), strictBudgetGate, budgetEnforced: strictBudgetGate.budgetEnforced === true, promptBodiesStored: false, outputBodiesStored: false };
+}
+
+function countQueueFiles(dir: string): number {
+  return existsSync(dir) ? readdirSync(dir).filter((file) => file.endsWith(".json")).length : 0;
+}
+
+function readQueueLedger(repoRoot: string): Array<Record<string, unknown>> {
+  const ledger = getQueuePaths(repoRoot).ledger;
+  if (!existsSync(ledger)) return [];
+  return readFileSync(ledger, "utf8")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        const parsed = JSON.parse(line) as unknown;
+        return isRecord(parsed) ? parsed : undefined;
+      } catch {
+        return undefined;
+      }
+    })
+    .filter((entry): entry is Record<string, unknown> => Boolean(entry));
+}
+
+export function buildQueueDashboardSummary(repoRoot: string, date?: string): Record<string, unknown> {
+  const paths = ensureQueueDirs(repoRoot);
+  const ledger = readQueueLedger(repoRoot);
+  const byEvent: Record<string, number> = {};
+  const byJobType: Record<string, number> = {};
+  for (const entry of ledger) {
+    incrementCounter(byEvent, stringFrom(entry.event));
+    incrementCounter(byJobType, stringFrom(entry.jobType));
+  }
+  const day = normalizeDailyTelemetryDate(date);
+  const dailyPath = join(repoRoot, ".pi", "logs", "summaries", `${day}.json`);
+  const daily = existsSync(dailyPath) && isRecord(parseJsonFile(dailyPath)) ? (parseJsonFile(dailyPath) as Record<string, unknown>) : undefined;
+  return {
+    schema: "zob.queue-dashboard-summary.v1",
+    generatedAt: new Date().toISOString(),
+    queue: {
+      pending: countQueueFiles(paths.pending),
+      running: countQueueFiles(paths.running),
+      done: countQueueFiles(paths.done),
+      failed: countQueueFiles(paths.failed),
+    },
+    lifecycle: { events: ledger.length, byEvent, byJobType, latest: ledger.slice(-5) },
+    telemetry: daily ? { date: day, totals: daily.totals, statusCounts: daily.statusCounts, bodySafety: daily.bodySafety } : { date: day, missing: true },
+    budgetEnforced: false,
+    autoStartDaemon: false,
+    continuousLoop: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+  };
+}