zob-harness 0.9.0 → 0.9.2

package/scripts/harness-intake/lib/run-init.mjs

@@ -0,0 +1,307 @@
+import { join } from "node:path";
+import { ensureDir, repoRel, resolveRunDir, writeJson, writeText } from "./cli-io.mjs";
+import { FACTORY_NAME, SCHEMA_PREFIX } from "./constants.mjs";
+
+export function initializeRun(spec) {
+  const runDir = resolveRunDir(spec.run_id);
+  const relRunDir = repoRel(runDir);
+  ensureDir(runDir);
+  for (const child of ["checkpoints", "outputs", "validation", "oracle", "generated-proposals/teams", "generated-proposals/agents", "generated-proposals/factories", "generated-proposals/kickoff", "kickoff", "tmux"]) {
+    ensureDir(join(runDir, child));
+  }
+  writeText(join(runDir, "request.md"), `# Harness Intake Request\n\n${spec.request}\n\nRequest hash: \`${spec.request_hash}\`\n`);
+  writeJson(join(runDir, "inferred-run-spec.json"), spec);
+  const manifest = {
+    schema: `${SCHEMA_PREFIX}.manifest.v1`,
+    factory: FACTORY_NAME,
+    run_id: spec.run_id,
+    mode: spec.mode,
+    run_dir: relRunDir,
+    target: spec.target,
+    harness_hint: spec.harness_hint,
+    goal: spec.goal,
+    sessions: spec.sessions,
+    output_policy: spec.output_policy,
+    expected_artifacts: [
+      "artifact-contracts.json",
+      "autonomous-status.md",
+      "sources-index.json",
+      "harness-profile.json",
+      "skills-profile.json",
+      "commands-profile.json",
+      "workflow-patterns.json",
+      "team-candidates.json",
+      "factory-candidates.json",
+      "validation.json",
+      "oracle-review.json",
+    ],
+    team: {
+      id: "harness-intake-team",
+      entry_agent: "harness-intake-orchestrator",
+      agents: HARNESS_INTAKE_AGENTS.map((agent) => agent.id),
+    },
+  };
+  writeJson(join(runDir, "manifest.json"), manifest);
+  writeJson(join(runDir, "agentic-plan.json"), buildAgenticPlan(spec, relRunDir));
+  writeJson(join(runDir, "artifact-contracts.json"), buildArtifactContracts(spec, relRunDir));
+  writeText(join(runDir, "autonomous-status.md"), renderAutonomousStatus(spec, relRunDir));
+  writeJson(join(runDir, "status.json"), {
+    schema: `${SCHEMA_PREFIX}.status.v1`,
+    run_id: spec.run_id,
+    status: "initialized",
+    no_ship: false,
+    phase: "init",
+    run_dir: relRunDir,
+    updated_at: new Date().toISOString(),
+  });
+  renderKickoffFiles(spec, runDir);
+  return { runDir, manifest };
+}
+
+export function buildArtifactContracts(spec, relRunDir) {
+  return {
+    schema: `${SCHEMA_PREFIX}.artifact-contracts.v1`,
+    run_id: spec.run_id,
+    run_dir: relRunDir,
+    room: "harness-intake-control",
+    entry_agent: "harness-intake-orchestrator",
+    startup_file_delivery_required: true,
+    raw_prompt_transport_line_by_line: false,
+    post_start_tmux_paste_disabled: true,
+    contracts: HARNESS_INTAKE_AGENTS.map((agent) => ({
+      agent: agent.id,
+      alias: agent.alias,
+      lane: agent.lane,
+      role: agent.role,
+      outputs: agent.outputFiles,
+      done_when: agent.doneWhen,
+      requires_authorization: agent.requiresAuthorization || null,
+    })),
+    final_gate: {
+      validation_ref: "validation.json",
+      oracle_review_ref: "oracle-review.json",
+      done_sentinel_ref: "DONE.sentinel",
+      completion_requires: [
+        "validation.json status=pass",
+        "oracle-review.json verdict PASS or WARN with no no-ship blockers",
+        "generated proposals remain quarantine-only",
+        "tmux kickoff-dispatch, when present, proves startup file delivery and no line-by-line prompt paste",
+      ],
+    },
+  };
+}
+
+export function renderAutonomousStatus(spec, relRunDir) {
+  return `# Harness Intake Autonomous Status
+
+Run id: ${spec.run_id}
+Run dir: ${relRunDir}
+Status: initialized
+No-ship: false
+Target: ${spec.target.input}
+Harness hint: ${spec.harness_hint}
+Sessions: ${spec.sessions.authorized ? "authorized" : spec.sessions.mentioned ? "mentioned but not authorized" : "not requested"}
+
+## Lanes
+
+${HARNESS_INTAKE_AGENTS.map((agent) => `- ${agent.id} (${agent.lane}): planned; outputs: ${agent.outputFiles.join(", ")}`).join("\n")}
+
+## Gates
+
+- Source project remains read-only.
+- Sessions require explicit authorization.
+- Generated teams/factories stay in generated-proposals/.
+- Tmux launch is startup/visibility only, not completion.
+`;
+}
+
+export function buildAgenticPlan(spec, relRunDir) {
+  return {
+    schema: `${SCHEMA_PREFIX}.agentic-plan.v1`,
+    run_id: spec.run_id,
+    run_dir: relRunDir,
+    control_plane: "natural-language-launcher-plus-supervised-agent-team",
+    deterministic_tools: ["scan-sources", "validate-run", "tmux-launch"],
+    stages: [
+      "infer_run_spec",
+      "source_cartography",
+      "harness_interpretation",
+      "skill_command_analysis",
+      "session_mining_if_authorized",
+      "workflow_pattern_mining",
+      "team_candidate_generation",
+      "factory_candidate_generation",
+      "oracle_validation",
+    ],
+    quarantine_only: true,
+    activation_enabled: false,
+    tmux_optional: true,
+  };
+}
+
+export const HARNESS_INTAKE_AGENTS = [
+  {
+    id: "harness-intake-orchestrator",
+    alias: "intake_chief",
+    lane: "control",
+    role: "Coordinate the full harness intake run and consolidate evidence.",
+    outputFiles: ["run-summary.md", "oracle-review.json"],
+    doneWhen: ["All required run artifacts exist or blockers are explicit.", "Validation/oracle posture is recorded."],
+  },
+  {
+    id: "harness-source-cartographer",
+    alias: "source_cartographer",
+    lane: "source",
+    role: "Map allowed setup sources and risk posture.",
+    outputFiles: ["sources-index.json", "source-risk-report.json"],
+    doneWhen: ["Source index exists.", "Forbidden/skipped paths and source risks are recorded."],
+  },
+  {
+    id: "harness-interpreter",
+    alias: "harness_interpreter",
+    lane: "harness",
+    role: "Interpret the external harness model and conventions.",
+    outputFiles: ["harness-profile.json"],
+    doneWhen: ["Harness model, conventions, unknowns, and ZOB mappings are evidence-backed."],
+  },
+  {
+    id: "harness-skill-command-analyst",
+    alias: "skill_command_analyst",
+    lane: "skills",
+    role: "Analyze skills, commands, prompts, and hooks.",
+    outputFiles: ["skills-profile.json", "commands-profile.json", "prompt-patterns.json"],
+    doneWhen: ["Skills/commands/prompts are mapped to possible ZOB roles, workflow steps, or validators."],
+  },
+  {
+    id: "harness-session-miner",
+    alias: "session_miner",
+    lane: "sessions",
+    role: "Mine authorized sessions without persisting raw conversation bodies.",
+    outputFiles: ["sessions-analysis.json", "session-evidence-index.json"],
+    doneWhen: ["Sessions are analyzed only when authorized, or a skip reason is recorded."],
+    requiresAuthorization: "sessions.authorized=true",
+  },
+  {
+    id: "harness-workflow-pattern-miner",
+    alias: "workflow_miner",
+    lane: "patterns",
+    role: "Detect reusable workflow patterns from static and behavioral evidence.",
+    outputFiles: ["workflow-patterns.json", "workflow-patterns.md"],
+    doneWhen: ["Workflow patterns include confidence, candidate flags, and evidence refs."],
+  },
+  {
+    id: "zob-team-architect",
+    alias: "team_architect",
+    lane: "teams",
+    role: "Generate ZOB team candidates in quarantine.",
+    outputFiles: ["team-candidates.json", "generated-proposals/teams", "generated-proposals/agents", "generated-proposals/kickoff"],
+    doneWhen: ["Team candidates remain quarantine-only and include activation blockers."],
+  },
+  {
+    id: "harness-factory-designer",
+    alias: "factory_designer",
+    lane: "factories",
+    role: "Generate factory candidates and activation blockers.",
+    outputFiles: ["factory-candidates.json", "generated-proposals/factories"],
+    doneWhen: ["Factory candidates define input contract, validators, smoke posture, and activation blockers."],
+  },
+  {
+    id: "harness-intake-oracle",
+    alias: "intake_oracle",
+    lane: "oracle",
+    role: "Validate evidence, privacy, quarantine posture, and no-ship status.",
+    outputFiles: ["validation.json", "oracle-review.json", "DONE.sentinel"],
+    doneWhen: ["Validation passes or no-ship blockers are explicit.", "Tmux launch is not treated as completion."],
+  },
+];
+
+export function renderKickoffFiles(spec, runDir) {
+  for (const agent of HARNESS_INTAKE_AGENTS) {
+    const isChief = agent.id === "harness-intake-orchestrator";
+    const artifactRefs = {
+      manifest: repoRel(join(runDir, "manifest.json")),
+      runSpec: repoRel(join(runDir, "inferred-run-spec.json")),
+      artifactContracts: repoRel(join(runDir, "artifact-contracts.json")),
+      status: repoRel(join(runDir, "autonomous-status.md")),
+      generatedProposals: repoRel(join(runDir, "generated-proposals")),
+    };
+    const body = `# Harness Intake Kickoff — ${agent.id}
+
+Run id: ${spec.run_id}
+Target: ${spec.target.input}
+Harness hint: ${spec.harness_hint}
+Lane: ${agent.lane}
+Alias: @${agent.alias}
+Run manifest: ${artifactRefs.manifest}
+Run spec: ${artifactRefs.runSpec}
+Artifact contracts: ${artifactRefs.artifactContracts}
+Status: ${artifactRefs.status}
+Generated proposals: ${artifactRefs.generatedProposals}
+
+This startup file is the complete task contract. It is passed as \`pi @<kickoff-file>\`; tmux must not paste this prompt line-by-line.
+
+## READY handshake — first action
+
+If live peer messaging is available, send a short READY/STATUS_UPDATE to @intake_chief. If not, write your status to the run status/artifact lane and continue.
+
+\`\`\`text
+READY
+agent: ${agent.id}
+run_id: ${spec.run_id}
+lane: ${agent.lane}
+owned_outputs:
+${agent.outputFiles.map((file) => `- ${file}`).join("\n")}
+blockers: none|...
+\`\`\`
+
+## TASK
+
+${agent.role}
+${isChief ? "Coordinate the full run, keep artifacts canonical, and make sure blocked lanes are visible." : "Read upstream run artifacts and produce/validate your owned slice only."}
+
+## EXPECTED OUTCOME
+
+Owned outputs are present, evidence-backed, and safe for downstream team/factory proposal review.
+
+## MUST DO
+
+- Read the run manifest, run spec, artifact contracts, and status before conclusions.
+- Keep source project reads bounded and read-only.
+- Cite artifact/source refs for every important claim.
+- Keep generated content under the run directory, especially generated-proposals/.
+- Mark blockers instead of inventing missing evidence.
+${agent.requiresAuthorization ? "- Verify sessions.authorized=true before reading any sessions. If not authorized, record skip/blocker only." : "- Treat session artifacts as unavailable unless authorization is recorded."}
+
+## MUST NOT
+
+- Do not read secrets, credentials, env files, keys, SSH/AWS config, vendor folders, or build artifacts.
+- Do not mutate the source project.
+- Do not persist raw session bodies in generated prompts or proposals.
+- Do not activate generated teams/factories automatically.
+- Do not treat tmux launch as completion.
+
+## OUTPUT FILES
+
+${agent.outputFiles.map((file) => `- ${file}`).join("\n")}
+
+## DONE WHEN
+
+${agent.doneWhen.map((item) => `- ${item}`).join("\n")}
+
+## Final claim shape
+
+\`\`\`text
+ARTIFACT_READY
+agent: ${agent.id}
+run_id: ${spec.run_id}
+outputs:
+- <path>
+validation:
+- <command or artifact check>
+blockers: none|...
+needs_review: yes/no
+\`\`\`
+`;
+    writeText(join(runDir, "kickoff", `${agent.id}-kickoff.md`), body);
+  }
+}

package/scripts/harness-intake/lib/scan.mjs

@@ -0,0 +1,266 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, extname, join, relative, sep } from "node:path";
+import { sha256 } from "./cli-io.mjs";
+import { DEFAULT_FORBIDDEN, MAX_FILE_BYTES, MAX_SCAN_FILES, SCHEMA_PREFIX, TEXT_EXTENSIONS } from "./constants.mjs";
+
+export function scanSources(spec) {
+  const targetRoot = spec.target.path;
+  const files = [];
+  const skipped = [];
+  const startedAt = new Date().toISOString();
+  walkRelevant(targetRoot, spec, files, skipped);
+  const limited = files.slice(0, MAX_SCAN_FILES);
+  if (files.length > limited.length) skipped.push({ path: "<scan-limit>", reason: `max_scan_files>${MAX_SCAN_FILES}`, omitted_count: files.length - limited.length });
+  const sources = limited.map((file, index) => inspectSourceFile(targetRoot, file, index, spec));
+  const harnesses = summarizeHarnesses(sources, spec.harness_hint);
+  return {
+    schema: `${SCHEMA_PREFIX}.sources-index.v1`,
+    run_id: spec.run_id,
+    target: spec.target,
+    scanned_at: startedAt,
+    source_project_modified: false,
+    raw_secret_storage: false,
+    session_authorized: spec.sessions.authorized,
+    source_count: sources.length,
+    sources,
+    harnesses,
+    skipped,
+  };
+}
+
+export function walkRelevant(root, spec, files, skipped) {
+  function visit(dir, depth) {
+    if (files.length >= MAX_SCAN_FILES * 2) return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch (error) {
+      skipped.push({ path: safeRel(root, dir), reason: `read_error:${error.message}` });
+      return;
+    }
+    for (const entry of entries) {
+      const full = join(dir, entry.name);
+      const relPath = safeRel(root, full);
+      const forbidden = pathForbidden(relPath, DEFAULT_FORBIDDEN);
+      if (forbidden) {
+        skipped.push({ path: relPath, reason: `forbidden:${forbidden}`, directory: entry.isDirectory() });
+        continue;
+      }
+      if (entry.isDirectory()) {
+        if (!isRelevantDirectory(relPath, spec) && depth > 1) {
+          skipped.push({ path: relPath, reason: "not_harness_relevant_directory", directory: true });
+          continue;
+        }
+        visit(full, depth + 1);
+        continue;
+      }
+      if (!entry.isFile()) {
+        skipped.push({ path: relPath, reason: "not_regular_file" });
+        continue;
+      }
+      if (!isRelevantFile(relPath, spec)) {
+        skipped.push({ path: relPath, reason: "not_harness_relevant_file" });
+        continue;
+      }
+      const size = statSync(full).size;
+      if (size > MAX_FILE_BYTES) {
+        skipped.push({ path: relPath, reason: `too_large>${MAX_FILE_BYTES}` });
+        continue;
+      }
+      if (!TEXT_EXTENSIONS.has(extname(entry.name).toLowerCase()) && !isExtensionlessRelevant(relPath)) {
+        skipped.push({ path: relPath, reason: "unsupported_extension" });
+        continue;
+      }
+      files.push({ full, relPath, size });
+    }
+  }
+  visit(root, 0);
+}
+
+export function safeRel(root, full) {
+  const rel = relative(root, full).split(sep).join("/");
+  return rel || ".";
+}
+
+export function isRelevantDirectory(relPath, spec) {
+  const normalized = relPath.toLowerCase();
+  if (normalized === ".") return true;
+  if (isSessionLikePath(normalized) && !spec.sessions.authorized) return false;
+  if (normalized.startsWith(".claude") || normalized.startsWith(".codex") || normalized.startsWith(".cursor")) return true;
+  if (normalized.startsWith(".pi/agents") || normalized.startsWith(".pi/zagents") || normalized.startsWith(".pi/skills") || normalized.startsWith(".pi/prompts") || normalized.startsWith(".pi/teams") || normalized.startsWith(".pi/zteams") || normalized.startsWith(".pi/factories")) return true;
+  if (/^(docs?|prompts?|skills?|commands?|agents?|scripts?|workflows?|hooks?)(\/|$)/.test(normalized)) return true;
+  if (spec.sessions.authorized && /(^|\/)(sessions?|transcripts?|conversation-history)(\/|$)/.test(normalized)) return true;
+  return false;
+}
+
+export function isRelevantFile(relPath, spec) {
+  const normalized = relPath.toLowerCase();
+  const base = basename(normalized);
+  if (isSessionLikePath(normalized) && !spec.sessions.authorized) return false;
+  if (["agents.md", "claude.md", "codex.md", "gemini.md", "readme.md", "package.json", "package-lock.json", "pnpm-lock.yaml", "yarn.lock", ".aider.conf.yml", ".aider.conf.yaml", ".aider.model.settings.yml"].includes(base)) return true;
+  if (/\.(team|factory)\.json$/.test(normalized)) return true;
+  if (/(kickoff|prompt|agent|team|factory|tmux|workflow|command|skill).*(\.template)?\.(md|json|ya?ml|toml|sh|mjs|js|ts)$/.test(normalized)) return true;
+  if (normalized.startsWith(".claude/") || normalized.startsWith(".codex/") || normalized.startsWith(".cursor/")) return true;
+  if (normalized.startsWith(".pi/agents/") || normalized.startsWith(".pi/zagents/") || normalized.startsWith(".pi/skills/") || normalized.startsWith(".pi/prompts/") || normalized.startsWith(".pi/teams/") || normalized.startsWith(".pi/zteams/") || normalized.startsWith(".pi/factories/")) return true;
+  if (/^(docs?|prompts?|skills?|commands?|agents?|scripts?|workflows?|hooks?)(\/|$)/.test(normalized)) return true;
+  if (spec.sessions.authorized && /(^|\/)(sessions?|transcripts?|conversation-history)(\/|$)/.test(normalized)) return true;
+  return false;
+}
+
+export function isSessionLikePath(normalizedRelPath) {
+  return /(^|\/)(sessions?|transcripts?|conversation-history|conversation_history|chat-history|chat_history)(\/|$)/.test(normalizedRelPath);
+}
+
+export function isExtensionlessRelevant(relPath) {
+  return ["agents", "claude", "codex", "readme"].includes(basename(relPath).toLowerCase());
+}
+
+export function pathForbidden(relPath, forbiddenPatterns) {
+  const normalized = relPath.split(sep).join("/");
+  const segments = normalized.split("/").filter(Boolean);
+  for (const pattern of forbiddenPatterns) {
+    const clean = String(pattern).replace(/\\/g, "/").replace(/\/$/, "");
+    if (!clean) continue;
+    if (clean.includes("/")) {
+      if (normalized === clean || normalized.startsWith(`${clean}/`)) return clean;
+      continue;
+    }
+    for (const segment of segments) {
+      if (segmentMatches(segment, clean)) return clean;
+    }
+  }
+  return null;
+}
+
+export function segmentMatches(segment, pattern) {
+  if (pattern.startsWith("*")) return segment.endsWith(pattern.slice(1));
+  if (pattern.endsWith("*")) return segment.startsWith(pattern.slice(0, -1));
+  return segment === pattern;
+}
+
+export function inspectSourceFile(root, file, index, spec) {
+  const text = safeRead(file.full);
+  const lines = text.split(/\r?\n/u);
+  const sourceId = `S-${String(index + 1).padStart(4, "0")}`;
+  const type = classifySource(file.relPath, spec);
+  const harness = detectHarness(file.relPath, text, spec.harness_hint);
+  const signals = extractSignals(file.relPath, lines);
+  const secretLike = detectSecretLike(file.relPath, text);
+  return {
+    source_id: sourceId,
+    path: file.relPath,
+    absolute_path_hash: sha256(file.full),
+    type,
+    harness,
+    size_bytes: file.size,
+    lines: lines.length,
+    content_hash: sha256(text),
+    contains_possible_secret: secretLike.length > 0,
+    secret_like_reasons: secretLike,
+    citations: signals.slice(0, 12),
+    used_for: usageForType(type),
+  };
+}
+
+export function safeRead(path) {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+export function classifySource(relPath, spec) {
+  const lower = relPath.toLowerCase();
+  const base = basename(lower);
+  if (spec.sessions.authorized && /(^|\/)(sessions?|transcripts?|conversation-history)(\/|$)/.test(lower)) return "session";
+  if (lower.startsWith(".pi/zagents/prompts/") || lower.includes("/zagents/prompts/")) return "zagent-prompt";
+  if (lower.startsWith(".pi/zagents/") || lower.includes("/zagents/")) return "zagent";
+  if ((lower.startsWith(".pi/zteams/") || lower.includes("/zteams/")) && lower.endsWith(".tmux.sh")) return "zteam-launcher";
+  if ((lower.startsWith(".pi/zteams/") || lower.includes("/zteams/")) && /runtime\.(mjs|js|ts)$/.test(lower)) return "zteam-runtime";
+  if (lower.startsWith(".pi/zteams/") || lower.includes("/zteams/")) return "zteam";
+  if (base === "agents.md" || lower.includes("/agents/") || lower.startsWith(".pi/agents/")) return "agent-definition";
+  if (base === "claude.md" || base === "codex.md" || base === "gemini.md") return "harness-instructions";
+  if (lower.includes("/skills/") || lower.startsWith(".pi/skills/")) return "skill";
+  if (lower.includes("/commands/") || lower.includes("/hooks/")) return "command";
+  if (lower.includes("/prompts/") || lower.includes("prompt")) return "prompt";
+  if (lower.includes("/teams/") || lower.endsWith(".team.json") || lower.includes("team")) return "team";
+  if (lower.includes("/factories/") || base === "factory.json" || lower.includes("factory")) return "factory";
+  if (base === "package.json") return "package-manifest";
+  if (lower.startsWith("scripts/") || lower.includes("/scripts/")) return "script";
+  if (lower.startsWith("docs/") || lower.includes("/docs/") || base === "readme.md") return "documentation";
+  return "config";
+}
+
+export function detectHarness(relPath, text, hint) {
+  const lower = `${relPath}\n${text.slice(0, 5000)}`.toLowerCase();
+  if (lower.includes("claude") || relPath.toLowerCase().startsWith(".claude/")) return "claude-code";
+  if (lower.includes("codex") || relPath.toLowerCase().startsWith(".codex/")) return "codex";
+  if (lower.includes("cursor") || relPath.toLowerCase().startsWith(".cursor/")) return "cursor";
+  if (lower.includes("aider")) return "aider";
+  if (lower.includes("zob") || lower.includes(" pi ") || relPath.toLowerCase().startsWith(".pi/")) return "pi-zob";
+  return hint || "unknown";
+}
+
+export function extractSignals(relPath, lines) {
+  const patterns = [
+    ["agent", /\bagents?\b|\bsub-?agents?\b|\bworker\b|\borchestrator\b/i],
+    ["skill", /\bskills?\b|\bcapabilit(y|ies)\b/i],
+    ["command", /\bcommands?\b|slash command|\/\w+/i],
+    ["tool", /\btools?\b|read|write|edit|bash|grep|find/i],
+    ["session", /\bsessions?\b|conversation|transcript|history/i],
+    ["workflow", /\bworkflow\b|\bplan\b|\bimplement\b|\breview\b|\boracle\b|validate/i],
+    ["factory", /\bfactory\b|factories|batch|smoke|pilot/i],
+    ["safety", /secret|credential|token|forbidden|must not|never|safety|no-ship/i],
+  ];
+  const citations = [];
+  lines.forEach((line, index) => {
+    for (const [kind, pattern] of patterns) {
+      if (pattern.test(line)) citations.push({ kind, ref: `${relPath}:L${index + 1}` });
+    }
+  });
+  return citations.slice(0, 48);
+}
+
+export function detectSecretLike(relPath, text) {
+  const reasons = [];
+  if (pathForbidden(relPath, DEFAULT_FORBIDDEN)) reasons.push("secret_like_path");
+  const probes = [
+    [/AKIA[0-9A-Z]{16}/, "aws_access_key_like"],
+    [/-----BEGIN (?:RSA |OPENSSH |EC |DSA )?PRIVATE KEY-----/, "private_key_like"],
+    [/(?:api[_-]?key|secret|token|password)\s*[:=]\s*["'][^"']{12,}/i, "credential_assignment_like"],
+  ];
+  for (const [pattern, reason] of probes) {
+    if (pattern.test(text)) reasons.push(reason);
+  }
+  return [...new Set(reasons)];
+}
+
+export function usageForType(type) {
+  const map = {
+    "agent-definition": ["harness-profile", "team-candidates"],
+    zagent: ["harness-profile", "team-candidates"],
+    "zagent-prompt": ["prompt-patterns", "team-candidates"],
+    zteam: ["team-candidates", "harness-profile"],
+    "zteam-launcher": ["commands-profile", "factory-candidates"],
+    "zteam-runtime": ["commands-profile", "factory-candidates", "workflow-patterns"],
+    "harness-instructions": ["harness-profile", "workflow-patterns"],
+    skill: ["skills-profile", "team-candidates"],
+    command: ["commands-profile", "workflow-patterns"],
+    prompt: ["prompt-patterns", "team-candidates"],
+    session: ["sessions-analysis", "workflow-patterns"],
+    team: ["team-candidates"],
+    factory: ["factory-candidates"],
+    "package-manifest": ["commands-profile"],
+    script: ["commands-profile", "factory-candidates"],
+    documentation: ["harness-profile", "workflow-patterns"],
+    config: ["harness-profile"],
+  };
+  return map[type] ?? ["harness-profile"];
+}
+
+export function summarizeHarnesses(sources, hint) {
+  const counts = new Map();
+  for (const source of sources) counts.set(source.harness, (counts.get(source.harness) ?? 0) + 1);
+  return [...counts.entries()].sort((a, b) => b[1] - a[1]).map(([name, count]) => ({ name, count, hint_match: name === hint }));
+}

package/scripts/harness-intake/lib/tmux.mjs

@@ -0,0 +1,92 @@
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { readJson, repoRel, resolveRunDir, safeRunId, sha256, writeJson } from "./cli-io.mjs";
+import { SCHEMA_PREFIX, repoRoot } from "./constants.mjs";
+import { HARNESS_INTAKE_AGENTS } from "./run-init.mjs";
+
+export function launchTmux(specOrRunDir, options = {}) {
+  const runDir = typeof specOrRunDir === "string" ? resolveRunDir(specOrRunDir) : resolveRunDir(specOrRunDir.run_id);
+  const spec = readJson(join(runDir, "inferred-run-spec.json"));
+  const sessionName = tmuxSessionName(spec.run_id);
+  const agents = HARNESS_INTAKE_AGENTS.map((agent) => agent.id);
+  if (options.command === "status") return tmuxStatus(sessionName, spec.run_id);
+  if (options.command === "attach") return tmuxAttach(sessionName, options.agent || agents[0]);
+  if (options.command === "stop") return tmuxStop(sessionName, spec.run_id);
+  requireTmux();
+  if (tmuxSessionExists(sessionName)) {
+    return { schema: `${SCHEMA_PREFIX}.tmux-result.v1`, status: "already-running", no_ship: false, run_id: spec.run_id, session: sessionName, attach_command: `npm run harness:intake:tmux -- attach ${spec.run_id}` };
+  }
+  const first = agents[0];
+  spawnTmux(["new-session", "-d", "-s", sessionName, "-n", first, "-c", repoRoot]);
+  const panes = [];
+  for (let i = 0; i < agents.length; i += 1) {
+    const agent = agents[i];
+    if (i !== 0) spawnTmux(["new-window", "-t", sessionName, "-n", agent, "-c", repoRoot]);
+    const kickoff = join(runDir, "kickoff", `${agent}-kickoff.md`);
+    const command = `cd ${shellQuote(repoRoot)} && HARNESS_INTAKE_RUN_ID=${shellQuote(spec.run_id)} ZOB_ZAGENT_ID=${shellQuote(agent)} ${process.env.PI_BIN || "pi"} @${shellQuote(kickoff)}`;
+    spawnTmux(["send-keys", "-t", `${sessionName}:${agent}`, command, "C-m"]);
+    panes.push({ agent, window: agent, kickoff_ref: repoRel(kickoff), command_hash: sha256(command) });
+  }
+  const dispatch = {
+    schema: `${SCHEMA_PREFIX}.kickoff-dispatch.v1`,
+    run_id: spec.run_id,
+    session: sessionName,
+    panes,
+    launched_at: new Date().toISOString(),
+    launch_is_not_completion: true,
+    startup_file_delivery: true,
+    worker_startup_file_delivery: true,
+    raw_prompt_transport_line_by_line: false,
+    post_start_tmux_paste_disabled: true,
+    transport: "pi @startup-kickoff.md for every harness-intake agent",
+  };
+  writeJson(join(runDir, "tmux", "kickoff-dispatch.json"), dispatch);
+  writeJson(join(runDir, "tmux", "session.json"), { schema: `${SCHEMA_PREFIX}.tmux-session.v1`, run_id: spec.run_id, session: sessionName, agents });
+  writeJson(join(runDir, "tmux", "panes.json"), { schema: `${SCHEMA_PREFIX}.tmux-panes.v1`, run_id: spec.run_id, panes });
+  return { schema: `${SCHEMA_PREFIX}.tmux-result.v1`, status: "started", no_ship: false, run_id: spec.run_id, session: sessionName, attach_command: `npm run harness:intake:tmux -- attach ${spec.run_id}` };
+}
+
+export function tmuxSessionName(runId) {
+  return `zob-harness-intake-${safeRunId(runId)}`;
+}
+
+export function requireTmux() {
+  const found = spawnSync("tmux", ["-V"], { encoding: "utf8" });
+  if (found.status !== 0) throw new Error("tmux is required for tmux mode");
+}
+
+export function spawnTmux(args) {
+  const result = spawnSync("tmux", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  if (result.status !== 0) throw new Error(`tmux ${args.join(" ")} failed: ${result.stderr.trim()}`);
+  return result.stdout.trim();
+}
+
+export function tmuxSessionExists(sessionName) {
+  const result = spawnSync("tmux", ["has-session", "-t", sessionName], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  return result.status === 0;
+}
+
+export function tmuxStatus(sessionName, runId) {
+  requireTmux();
+  if (!tmuxSessionExists(sessionName)) return { schema: `${SCHEMA_PREFIX}.tmux-status.v1`, status: "not-running", no_ship: false, run_id: runId, session: sessionName };
+  const list = spawnTmux(["list-windows", "-t", sessionName, "-F", "#{window_name}:#{pane_current_command}:#{pane_active}"]);
+  return { schema: `${SCHEMA_PREFIX}.tmux-status.v1`, status: "running", no_ship: false, run_id: runId, session: sessionName, windows: list.split("\n").filter(Boolean) };
+}
+
+export function tmuxAttach(sessionName, agent) {
+  requireTmux();
+  if (!tmuxSessionExists(sessionName)) return { schema: `${SCHEMA_PREFIX}.tmux-attach.v1`, status: "not-running", no_ship: true, session: sessionName };
+  const child = spawnSync("tmux", ["attach", "-t", `${sessionName}:${agent}`], { stdio: "inherit" });
+  return { schema: `${SCHEMA_PREFIX}.tmux-attach.v1`, status: child.status === 0 ? "attached" : "failed", no_ship: child.status !== 0, session: sessionName, agent };
+}
+
+export function tmuxStop(sessionName, runId) {
+  requireTmux();
+  if (!tmuxSessionExists(sessionName)) return { schema: `${SCHEMA_PREFIX}.tmux-stop.v1`, status: "not-running", no_ship: false, run_id: runId, session: sessionName };
+  spawnTmux(["kill-session", "-t", sessionName]);
+  return { schema: `${SCHEMA_PREFIX}.tmux-stop.v1`, status: "stopped", no_ship: false, run_id: runId, session: sessionName };
+}
+
+export function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}