opencode-feature-factory 0.2.0

package/src/env-snapshot.js

@@ -0,0 +1,211 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync, spawnSync } from "node:child_process";
+import { git } from "./git.js";
+import plugin from "./plugin.js";
+import { timestamp } from "./utils.js";
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const SENSITIVE_ENV_KEY_PATTERN = /(?:secret|token|password|passwd|pwd|api[_-]?key|private[_-]?key|credential|authorization|auth[_-]?header|access[_-]?key|bearer|cookie)/iu;
+const SENSITIVE_ENV_VALUE_PATTERN = /(?:secret|token|password|passwd|api[_-]?key|private[_-]?key)/iu;
+const TOKEN_SHAPED_ENV_VALUE_PATTERNS = [
+  /\bgh[pousr]_[A-Za-z0-9_]{20,}\b/u,
+  /\bgithub_pat_[A-Za-z0-9_]{20,}\b/u,
+  /\bhc_[A-Za-z0-9][A-Za-z0-9_-]{10,}\b/iu,
+  /\bsk-proj[-_][A-Za-z0-9_-]{20,}\b/u,
+  /\bsk-[A-Za-z0-9_-]{20,}\b/u,
+  /\bxox[abp][_-][A-Za-z0-9-]{10,}(?:-[A-Za-z0-9-]{10,})*\b/u,
+  /\bglpat-[A-Za-z0-9_-]{20,}\b/u,
+  /\bBearer\s+[A-Za-z0-9._~+/=-]{20,}\b/iu,
+  /\beyJ[A-Za-z0-9_-]{7,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/u,
+  /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/u,
+  /(?:^|[^A-Za-z0-9-])(?:[A-Fa-f0-9]{32,})(?=$|[^A-Za-z0-9-])/u,
+  /(?:https?|ssh|git|ftp):\/\/[^/\s:@]+:[^/\s@]+@/iu,
+];
+const HIGH_ENTROPY_SINGLE_TOKEN_MIN_LENGTH = 32;
+const HIGH_ENTROPY_MIN_SHANNON = 3.5;
+const SAFE_HIGH_ENTROPY_ENV_KEY_PATTERN = /^(?:OTEL_EXPORTER_OTLP(?:_(?:TRACES|METRICS|LOGS))?_(?:ENDPOINT|HEADERS|PROTOCOL|TIMEOUT|COMPRESSION|INSECURE|CERTIFICATE)|FEATURE_FACTORY_OTEL_ENABLED)$/u;
+export const REDACTED_ENV_VALUE = "[redacted]";
+
+export async function collectEnv(options = {}) {
+  const resolvedConfig = await resolvePluginConfig(options.pluginOptions || {});
+  return {
+    feature_factory_version: packageVersion(),
+    opencode_version: commandOutput("opencode", ["--version"]),
+    plugin_spec: options.pluginSpec || "opencode-feature-factory",
+    resolved_models: Object.fromEntries(Object.entries(resolvedConfig.agent || {}).map(([name, agent]) => [name, agent.model || null])),
+    resolved_variants: Object.fromEntries(Object.entries(resolvedConfig.agent || {}).map(([name, agent]) => [name, agent.variant || null])),
+    driver: {
+      kind: options.driverKind || "cli",
+      name: "feature-factory",
+      version: packageVersion(),
+    },
+    capabilities: detectCapabilities(options.cwd || process.cwd()),
+  };
+}
+
+export async function collectRunDebugSnapshot({ cwd, driverKind, pluginSpec, pluginOptions, event, now } = {}) {
+  return {
+    collected_at: timestamp(now, "environment snapshot timestamp"),
+    event: stringValue(event) ? event.trim() : "run-created",
+    diagnostic_only: true,
+    env: scrubSecretEnv(await collectEnv({ cwd, driverKind, pluginSpec, pluginOptions })),
+  };
+}
+
+export async function resolvePluginConfig(pluginOptions = {}) {
+  const hooks = await plugin({}, pluginOptions);
+  const cfg = {};
+  hooks.config(cfg);
+  return cfg;
+}
+
+export function detectCapabilities(cwd = process.cwd()) {
+  return {
+    git: commandOk("git", ["--version"]),
+    gh: commandOk("gh", ["--version"]),
+    gh_auth: commandOk("gh", ["auth", "status"]),
+    opencode: commandOk("opencode", ["--version"]),
+    opencode_run_command: opencodeRunSupports("--command"),
+    opencode_run_dir: opencodeRunSupports("--dir"),
+    git_repo: commandOk("git", ["rev-parse", "--show-toplevel"], cwd),
+    base_branch: detectBaseBranch(cwd),
+    factory_gitignored: gitIgnored(cwd, ".opencode/factory/"),
+    worktrees_gitignored: gitIgnored(cwd, ".opencode/worktrees/"),
+  };
+}
+
+export function scrubSecretEnv(value) {
+  if (Array.isArray(value)) return value.map((item) => scrubSecretEnv(item));
+  if (typeof value === "string") return isSensitiveEnvValue(value) ? REDACTED_ENV_VALUE : value;
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([key]) => !isSensitiveEnvKey(key))
+      .map(([key, item]) => [key, scrubSecretEnv(item)]),
+  );
+}
+
+export function isSensitiveEnvKey(key) {
+  const string = String(key ?? "");
+  return SENSITIVE_ENV_KEY_PATTERN.test(string) || isSecretShapedEnvKey(string);
+}
+
+export function isSensitiveEnvValue(value) {
+  if (typeof value !== "string") return false;
+  const trimmed = value.trim();
+  if (!trimmed) return false;
+  return SENSITIVE_ENV_VALUE_PATTERN.test(trimmed)
+    || TOKEN_SHAPED_ENV_VALUE_PATTERNS.some((pattern) => pattern.test(trimmed))
+    || credentialBearingUrl(trimmed)
+    || highEntropySingleToken(trimmed);
+}
+
+export function isSecretShapedEnvKey(key) {
+  const trimmed = String(key ?? "").trim();
+  if (!trimmed) return false;
+  return TOKEN_SHAPED_ENV_VALUE_PATTERNS.some((pattern) => pattern.test(trimmed))
+    || credentialBearingUrl(trimmed)
+    || highEntropySecretKey(trimmed);
+}
+
+function packageVersion() {
+  const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+  return pkg.version || "unknown";
+}
+
+function commandOk(command, args, cwd = process.cwd()) {
+  if (command === "git") return git(cwd, args).ok;
+  try {
+    execFileSync(command, args, { cwd, stdio: "ignore", timeout: 10000, maxBuffer: 1024 * 1024 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function commandOutput(command, args, cwd = process.cwd()) {
+  if (command === "git") {
+    const proc = git(cwd, args);
+    return proc.ok ? (proc.stdout || proc.stderr || "").trim() : null;
+  }
+  try {
+    return execFileSync(command, args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 10000, maxBuffer: 1024 * 1024 }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function opencodeRunSupports(flag) {
+  const help = opencodeRunHelpText();
+  if (!help) return false;
+  // Token-boundary match: a bare substring test would let '--dir' match a
+  // future '--directory' (or '--command' match '--commands') and report
+  // support that does not exist.
+  const escaped = flag.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+  return new RegExp(`(?:^|[\\s,=])${escaped}(?:$|[\\s,=])`, "mu").test(help);
+}
+
+// `opencode run --help` prints its usage to stderr and may exit non-zero, so
+// capture both streams instead of relying on stdout-only commandOutput().
+function opencodeRunHelpText() {
+  try {
+    const proc = spawnSync("opencode", ["run", "--help"], {
+      encoding: "utf8",
+      timeout: 10000,
+      maxBuffer: 1024 * 1024,
+    });
+    return `${proc.stdout || ""}\n${proc.stderr || ""}`.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function detectBaseBranch(cwd) {
+  const symbolic = commandOutput("git", ["symbolic-ref", "refs/remotes/origin/HEAD", "--short"], cwd);
+  if (symbolic) return symbolic.replace(/^origin\//u, "");
+  for (const candidate of ["main", "master", "development", "develop"]) {
+    if (commandOk("git", ["rev-parse", "--verify", `origin/${candidate}`], cwd)) return candidate;
+  }
+  return null;
+}
+
+function gitIgnored(cwd, path) {
+  if (!existsSync(join(cwd, ".git")) && !commandOk("git", ["rev-parse", "--show-toplevel"], cwd)) return null;
+  return commandOk("git", ["check-ignore", path], cwd);
+}
+
+function credentialBearingUrl(value) {
+  try {
+    const parsed = new URL(value);
+    return Boolean(parsed.username || parsed.password);
+  } catch {
+    return false;
+  }
+}
+
+function highEntropySingleToken(value) {
+  if (value.length < HIGH_ENTROPY_SINGLE_TOKEN_MIN_LENGTH) return false;
+  if (/\s/u.test(value)) return false;
+  if (!/^[A-Za-z0-9._~+/=-]+$/u.test(value)) return false;
+  return shannonEntropy(value) >= HIGH_ENTROPY_MIN_SHANNON;
+}
+
+function highEntropySecretKey(value) {
+  if (SAFE_HIGH_ENTROPY_ENV_KEY_PATTERN.test(value)) return false;
+  return highEntropySingleToken(value);
+}
+
+function shannonEntropy(value) {
+  const counts = new Map();
+  for (const char of value) counts.set(char, (counts.get(char) || 0) + 1);
+  return [...counts.values()].reduce((entropy, count) => {
+    const probability = count / value.length;
+    return entropy - probability * Math.log2(probability);
+  }, 0);
+}
+
+function stringValue(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}

package/src/factory-diagnostics.js

@@ -0,0 +1,429 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import {
+  TERMINAL_RUN_STATUSES,
+  pendingProtectedGate,
+  runSlicesMatchPlan,
+  validateFactoryLock,
+  validateHeartbeatState,
+  validateProcessSidecar,
+  validateRun,
+  validateSlicesPlan,
+} from "./validate.js";
+import { PROCESS_EVIDENCE_FILE } from "./process-evidence.js";
+import { hasInFlightHeartbeatWork } from "./run-state.js";
+import { physicalPath, timestamp } from "./utils.js";
+import { projectDiagnosticData } from "./hardening/output-policy.js";
+import {
+  probeLegacyBooleanLiveness,
+  probeProcessLiveness,
+  publicLivenessBoolean,
+} from "./hardening/process-verification.js";
+
+export const DIAGNOSTIC_SCHEMA_VERSION = 1;
+export const HEARTBEAT_FILE = "heartbeat.json";
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 30000;
+export const MIN_STALE_HEARTBEAT_MS = 120000;
+
+const CONDITIONS = Object.freeze([
+  Object.freeze({ condition: "invalid-run-state", classification: "invalid", severity: "critical", status: "error", message: "Factory run state is invalid or cannot be parsed.", action: "Treat the run as untrusted until run.json and required sidecars validate." }),
+  Object.freeze({ condition: "missing-worktree", classification: "blocked", severity: "error", status: "error", message: "A recorded worktree path is missing or inaccessible.", action: "Restore the worktree or complete cleanup/recovery from durable state." }),
+  Object.freeze({ condition: "missing-heartbeat-process", classification: "recoverable", severity: "warning", status: "warning", message: "The heartbeat helper process recorded in heartbeat.json is not alive.", action: "Inspect the run log and validate durable state before resuming; do not infer run failure from PID liveness alone." }),
+  Object.freeze({ condition: "stale-heartbeat", classification: "recoverable", severity: "warning", status: "warning", message: "Heartbeat has not advanced within the stale threshold.", action: "Inspect the run log and validate durable state before resuming; do not restart blindly." }),
+  Object.freeze({ condition: "protected-gate", classification: "needs-human", severity: "warning", status: "warning", message: "Run is waiting at a protected human gate.", action: "Answer the pending protected gate or stop the run; heartbeat liveness alarms are suppressed while waiting." }),
+  Object.freeze({ condition: "terminal-run", classification: "terminal", severity: "info", status: "ok", message: "Run is terminal.", action: "Read terminal_result for the durable outcome." }),
+]);
+
+export const DIAGNOSTIC_CONDITIONS = Object.freeze(CONDITIONS.map((item) => item.condition));
+export const DIAGNOSTIC_CLASSIFICATIONS = Object.freeze(["healthy", "recoverable", "blocked", "needs-human", "terminal", "invalid"]);
+export const DIAGNOSTIC_STATUSES = Object.freeze(["ok", "warning", "error"]);
+export const DIAGNOSTIC_SEVERITIES = Object.freeze(["info", "warning", "error", "critical"]);
+
+const CONDITION_BY_NAME = new Map(CONDITIONS.map((item, index) => [item.condition, { ...item, index }]));
+const TERMINAL_OVERRIDES = Object.freeze({
+  completed: Object.freeze({ classification: "terminal", severity: "info", status: "ok" }),
+  partial: Object.freeze({ classification: "terminal", severity: "info", status: "ok" }),
+  blocked: Object.freeze({ classification: "blocked", severity: "error", status: "error" }),
+  "needs-human": Object.freeze({ classification: "needs-human", severity: "warning", status: "warning" }),
+});
+
+const TERMINAL_STATUSES = new Set(TERMINAL_RUN_STATUSES);
+const DIAGNOSTIC_IDENTITY_FIELDS = Object.freeze({
+  status: new Set(DIAGNOSTIC_STATUSES),
+  severity: new Set(DIAGNOSTIC_SEVERITIES),
+  classification: new Set(DIAGNOSTIC_CLASSIFICATIONS),
+  condition: new Set(DIAGNOSTIC_CONDITIONS),
+});
+
+export function diagnoseRunDir(runDir, options = {}) {
+  return diagnoseRunFile(join(runDir, "run.json"), { ...options, runDir });
+}
+
+export function diagnoseRunFile(runFile, options = {}) {
+  const runDir = options.runDir || dirname(runFile);
+  const checkedAt = timestamp(options.now);
+  let raw;
+
+  try {
+    raw = readFileSync(runFile, "utf8");
+  } catch (error) {
+    return diagnosticEnvelope([
+      diagnosticItem("invalid-run-state", {
+        checkedAt,
+        authoritative: false,
+        message: `Factory run state is unavailable: ${error.message}`,
+        evidence: { source: "run.json", run_dir: runDir, run_path: runFile, error: error.message },
+      }),
+    ], { checkedAt, authoritative: false });
+  }
+
+  try {
+    return diagnoseRunObject(JSON.parse(raw), { ...options, runDir, runFile, checkedAt });
+  } catch (error) {
+    return diagnosticEnvelope([
+      diagnosticItem("invalid-run-state", {
+        checkedAt,
+        authoritative: false,
+        message: `Factory run state is invalid: ${error.message}`,
+        evidence: { source: "run.json", run_dir: runDir, run_path: runFile, error: error.message },
+      }),
+    ], { checkedAt, authoritative: false });
+  }
+}
+
+export function diagnoseRunObject(input, options = {}) {
+  const checkedAt = options.checkedAt || timestamp(options.now);
+  const runDir = options.runDir || null;
+  const runFile = options.runFile || (runDir ? join(runDir, "run.json") : null);
+  const items = [];
+  let run;
+
+  try {
+    run = validateRun(input);
+  } catch (error) {
+    return diagnosticEnvelope([
+      diagnosticItem("invalid-run-state", {
+        checkedAt,
+        authoritative: false,
+        message: `Factory run state is invalid: ${error.message}`,
+        evidence: { source: "run.json", run_dir: runDir, run_path: runFile, error: error.message },
+      }),
+    ], { checkedAt, authoritative: false });
+  }
+
+  const invalidSidecar = runDir ? inspectSidecars(runDir, checkedAt, run) : null;
+  if (invalidSidecar) {
+    return diagnosticEnvelope([invalidSidecar], { checkedAt, authoritative: false });
+  }
+
+  const terminal = TERMINAL_STATUSES.has(run.status);
+  const authoritative = Boolean(runDir);
+  const protectedGate = pendingProtectedGate(run);
+
+  if (terminal) {
+    items.push(terminalRunItem(run, { checkedAt, runDir, runFile, authoritative }));
+    return diagnosticEnvelope(items, { checkedAt, authoritative });
+  }
+
+  if (protectedGate) {
+    items.push(diagnosticItem("protected-gate", {
+      checkedAt,
+      authoritative,
+      message: `Run is waiting at protected gate '${protectedGate}'.`,
+      evidence: { source: "run.json", run_dir: runDir, run_path: runFile, gate: protectedGate },
+    }));
+  } else if (hasInFlightHeartbeatWork(run)) {
+    const heartbeat = inspectHeartbeat(run, { ...options, checkedAt, runDir });
+    if (heartbeat.invalid) {
+      items.push(diagnosticItem("invalid-run-state", {
+        checkedAt,
+        authoritative: false,
+        message: `Heartbeat state is invalid: ${heartbeat.error}`,
+        evidence: { source: "heartbeat.json", run_dir: runDir, heartbeat_path: heartbeat.path, error: heartbeat.error },
+      }));
+    } else {
+      if (heartbeat.missingProcess) items.push(heartbeat.missingProcess);
+      if (heartbeat.stale) items.push(heartbeat.stale);
+    }
+  }
+
+  const missingWorktree = inspectWorktree(run, { ...options, checkedAt, runDir, authoritative });
+  if (missingWorktree) items.push(missingWorktree);
+
+  return diagnosticEnvelope(items, { checkedAt, authoritative });
+}
+
+export function diagnosticEnvelope(items = [], options = {}) {
+  const checkedAt = options.checkedAt || timestamp(options.now);
+  const normalized = items.map((item) => normalizeDiagnosticItem(item, checkedAt));
+  const aggregate = aggregateDiagnostics(normalized);
+  const envelope = {
+    schema_version: DIAGNOSTIC_SCHEMA_VERSION,
+    checked_at: checkedAt,
+    authoritative: Boolean(options.authoritative) && aggregate.classification !== "invalid",
+    status: aggregate.status,
+    severity: aggregate.severity,
+    classification: aggregate.classification,
+    summary: aggregate.summary,
+    items: normalized,
+  };
+  return plainDiagnosticProjection(projectDiagnosticData(envelope, {
+    validatedIdentityPaths: validatedDiagnosticIdentityPaths(envelope),
+  }));
+}
+
+export function aggregateDiagnostics(items = []) {
+  if (!items.length) {
+    return { classification: "healthy", status: "ok", severity: "info", summary: "No diagnostics", primary: null };
+  }
+  const primary = items
+    .map((item, index) => ({ item, index }))
+    .sort((left, right) => conditionOrder(left.item.condition) - conditionOrder(right.item.condition) || left.index - right.index)[0].item;
+  return {
+    classification: primary.classification,
+    status: primary.status,
+    severity: primary.severity,
+    summary: primary.message,
+    primary,
+  };
+}
+
+export function diagnosticItem(condition, options = {}) {
+  const definition = condition === "terminal-run"
+    ? terminalDefinition(options.terminalStatus)
+    : CONDITION_BY_NAME.get(condition);
+  if (!definition) throw new Error(`unknown diagnostic condition: ${condition}`);
+  const checkedAt = options.checkedAt || timestamp(options.now);
+  return normalizeDiagnosticItem({
+    condition,
+    classification: definition.classification,
+    severity: definition.severity,
+    status: definition.status,
+    message: options.message || definition.message,
+    action: options.action || definition.action || terminalAction(options.terminalStatus),
+    authoritative: Boolean(options.authoritative),
+    checked_at: checkedAt,
+    evidence: options.evidence || {},
+  }, checkedAt);
+}
+
+function normalizeDiagnosticItem(item, checkedAt) {
+  return {
+    condition: item.condition,
+    classification: item.classification,
+    severity: item.severity,
+    status: item.status,
+    message: item.message,
+    action: item.action,
+    authoritative: Boolean(item.authoritative),
+    checked_at: item.checked_at || checkedAt,
+    evidence: item.evidence && typeof item.evidence === "object" && !Array.isArray(item.evidence) ? item.evidence : {},
+  };
+}
+
+function terminalRunItem(run, options) {
+  return diagnosticItem("terminal-run", {
+    ...options,
+    terminalStatus: run.status,
+    message: terminalMessage(run.status),
+    evidence: { source: "run.json", run_dir: options.runDir, run_path: options.runFile, run_status: run.status },
+  });
+}
+
+function inspectSidecars(runDir, checkedAt, run) {
+  const checks = [
+    { path: join(runDir, HEARTBEAT_FILE), source: HEARTBEAT_FILE, validator: validateHeartbeatState },
+    { path: join(runDir, "factory.lock"), source: "factory.lock", validator: validateFactoryLock },
+    { path: join(runDir, PROCESS_EVIDENCE_FILE), source: PROCESS_EVIDENCE_FILE, validator: (value) => validateProcessSidecar(value, { runDir, runId: run.run_id }), failClosed: true },
+    { path: join(runDir, "plan", "slices.json"), source: "plan/slices.json", validator: (value) => validateSlicesPlan(value, { enforceDependencyDepth: !runSlicesMatchPlan(run, value) }) },
+  ];
+  for (const check of checks) {
+    if (!existsSync(check.path)) continue;
+    let parsed = null;
+    try {
+      parsed = JSON.parse(readFileSync(check.path, "utf8"));
+      const sidecar = check.validator(parsed);
+      if ((check.source === HEARTBEAT_FILE || check.source === "factory.lock") && sidecar.run_id !== run.run_id) {
+        return diagnosticItem("invalid-run-state", {
+          checkedAt,
+          authoritative: false,
+          message: `Factory sidecar state contradicts run.json: ${check.source}.run_id does not match run.run_id.`,
+          evidence: {
+            source: check.source,
+            run_dir: runDir,
+            path: check.path,
+            error: `${check.source}.run_id does not match run.run_id`,
+            run_id: run.run_id,
+            sidecar_run_id: sidecar.run_id,
+          },
+        });
+      }
+    } catch (error) {
+      const failClosed = Boolean(check.failClosed);
+      return diagnosticItem("invalid-run-state", {
+        checkedAt,
+        authoritative: false,
+        message: failClosed
+          ? `Factory process sidecar state is invalid; cancellation must fail closed: ${error.message}`
+          : `Factory sidecar state is invalid: ${error.message}`,
+        action: failClosed
+          ? "Treat process evidence as untrusted; do not signal any process until the sidecar is repaired or manually verified."
+          : undefined,
+        evidence: {
+          source: check.source,
+          run_dir: runDir,
+          path: check.path,
+          error: error.message,
+          ...(failClosed ? { fail_closed: true, sidecar_run_id: parsed?.run_id || null } : {}),
+        },
+      });
+    }
+  }
+  return null;
+}
+
+function inspectHeartbeat(run, options) {
+  const checkedAt = options.checkedAt;
+  const runDir = options.runDir;
+  const heartbeatPath = runDir ? join(runDir, HEARTBEAT_FILE) : null;
+  const nowMs = Date.parse(checkedAt);
+  let heartbeat = null;
+  let source = "run.json";
+
+  if (heartbeatPath && existsSync(heartbeatPath)) {
+    try {
+      heartbeat = validateHeartbeatState(JSON.parse(readFileSync(heartbeatPath, "utf8")));
+      if (heartbeat.run_id !== run.run_id) {
+        return { invalid: true, error: "heartbeat.run_id does not match run.run_id", path: heartbeatPath };
+      }
+      source = "heartbeat.json";
+    } catch (error) {
+      return { invalid: true, error: error.message, path: heartbeatPath };
+    }
+  }
+
+  const lastTickAt = heartbeat?.last_tick_at || run.heartbeat_at || null;
+  const intervalMs = positiveInteger(heartbeat?.interval_ms) || DEFAULT_HEARTBEAT_INTERVAL_MS;
+  const staleMs = Math.max(2 * intervalMs, MIN_STALE_HEARTBEAT_MS);
+  const lastTickMs = Date.parse(lastTickAt || "");
+  const ageMs = Number.isFinite(nowMs) && Number.isFinite(lastTickMs) ? Math.max(0, nowMs - lastTickMs) : null;
+  const evidence = {
+    source,
+    liveness_only: true,
+    run_dir: runDir,
+    heartbeat_path: heartbeatPath,
+    heartbeat_phase: heartbeat?.phase || null,
+    pid: heartbeat?.pid || null,
+    process_alive: null,
+    last_tick_at: lastTickAt,
+    interval_ms: intervalMs,
+    stale_after: Number.isFinite(lastTickMs) ? new Date(lastTickMs + staleMs).toISOString() : null,
+    age_ms: ageMs,
+  };
+
+  const result = {};
+  if (heartbeat) {
+    const liveness = processLiveness(heartbeat.pid, options);
+    evidence.process_alive = publicLivenessBoolean(liveness);
+    if (liveness === "absent") result.missingProcess = diagnosticItem("missing-heartbeat-process", {
+      checkedAt,
+      authoritative: false,
+      evidence: { ...evidence },
+    });
+  }
+
+  if (ageMs !== null && ageMs > staleMs) {
+    result.stale = diagnosticItem("stale-heartbeat", {
+      checkedAt,
+      authoritative: false,
+      evidence,
+    });
+  }
+  return result;
+}
+
+function inspectWorktree(run, options) {
+  if (!stringValue(run.worktree)) return null;
+  const repoRoot = options.repoRoot || options.cwd || process.cwd();
+  const worktree = isAbsolute(run.worktree) ? run.worktree : resolve(repoRoot, run.worktree);
+  try {
+    const physical = realpath(options, worktree);
+    if (!statSync(physical).isDirectory()) throw new Error(`worktree is not a directory: ${worktree}`);
+    return null;
+  } catch (error) {
+    return diagnosticItem("missing-worktree", {
+      checkedAt: options.checkedAt,
+      authoritative: options.authoritative,
+      evidence: {
+        source: "filesystem",
+        run_dir: options.runDir,
+        worktree,
+        error: error.message,
+      },
+    });
+  }
+}
+
+function processLiveness(pid, options = {}) {
+  if (typeof options.processAliveFn === "function") {
+    return probeLegacyBooleanLiveness(options.processAliveFn, pid);
+  }
+  return probeProcessLiveness(pid, options).status;
+}
+
+function validatedDiagnosticIdentityPaths(envelope) {
+  const paths = [];
+  for (const field of ["status", "severity", "classification"]) {
+    if (DIAGNOSTIC_IDENTITY_FIELDS[field].has(envelope[field])) paths.push([field]);
+  }
+  for (let index = 0; index < envelope.items.length; index += 1) {
+    const item = envelope.items[index];
+    for (const field of ["condition", "status", "severity", "classification"]) {
+      if (DIAGNOSTIC_IDENTITY_FIELDS[field].has(item[field])) paths.push(["items", String(index), field]);
+    }
+  }
+  return paths;
+}
+
+function plainDiagnosticProjection(value) {
+  if (Array.isArray(value)) return value.map(plainDiagnosticProjection);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, plainDiagnosticProjection(item)]));
+  }
+  return value;
+}
+
+function realpath(options, path) {
+  if (typeof options.realpathFn === "function") return options.realpathFn(path);
+  return physicalPath(path, "worktree", { mustExist: true });
+}
+
+function terminalDefinition(status) {
+  return { ...CONDITION_BY_NAME.get("terminal-run"), ...(TERMINAL_OVERRIDES[status] || TERMINAL_OVERRIDES.completed) };
+}
+
+function terminalMessage(status) {
+  if (status === "completed") return "Run completed.";
+  if (status === "partial") return "Run ended with a partial result.";
+  if (status === "blocked") return "Run ended blocked.";
+  if (status === "needs-human") return "Run is terminal and needs human attention.";
+  return "Run is terminal.";
+}
+
+function terminalAction(status) {
+  if (status === "completed" || status === "partial") return "No liveness action is required.";
+  if (status === "blocked") return "Inspect the terminal result and resolve the blocker before attempting follow-up work.";
+  return "Inspect the terminal result and provide the required human input.";
+}
+
+function conditionOrder(condition) {
+  return CONDITION_BY_NAME.get(condition)?.index ?? Number.MAX_SAFE_INTEGER;
+}
+
+function positiveInteger(value) {
+  return Number.isInteger(value) && value > 0 ? value : null;
+}
+
+function stringValue(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}

package/src/factory-paths.js

@@ -0,0 +1,40 @@
+import { statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { repoRoot } from "./git.js";
+
+export function directFactoryRoot(cwd = process.cwd()) {
+  const local = join(resolve(cwd), ".opencode", "factory");
+  if (isDirectory(local)) return local;
+  return join(repoRoot(cwd), ".opencode", "factory");
+}
+
+export function factoryRootsForLookup(cwd = process.cwd()) {
+  const direct = directFactoryRoot(cwd);
+  const roots = [direct];
+  const ancestor = nearestAncestorFactoryRoot(cwd);
+  if (ancestor && ancestor !== direct) roots.push(ancestor);
+  return roots;
+}
+
+export function factoryRepoFromRunDir(runDir) {
+  return dirname(dirname(dirname(resolve(runDir))));
+}
+
+function nearestAncestorFactoryRoot(cwd) {
+  let dir = resolve(cwd);
+  while (true) {
+    const candidate = join(dir, ".opencode", "factory");
+    if (isDirectory(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function isDirectory(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}