subconscious-cli 6.0.1 → 6.2.0

package/bin/auth.js

@@ -401,7 +401,7 @@ export async function whoamiCommand(_argv = [], options = {}) {
       }
       console.log(`  ${c.dim}Key:    ${masked}${c.reset}`);
       console.log(`  ${c.dim}Source: ${source}${c.reset}`);
-    } else {
+    } else if (res.status === 401) {
       console.log(`  ${c.red}✗ Key is invalid or revoked${c.reset}`);
       console.log(`  ${c.dim}Key:    ${masked}${c.reset}`);
       console.log(`  ${c.dim}Source: ${source}${c.reset}`);
@@ -409,6 +409,14 @@ export async function whoamiCommand(_argv = [], options = {}) {
       console.log(
         `  Run ${c.cyan}subc ${profileFlag}logout${c.reset} then ${c.cyan}subc ${profileFlag}login${c.reset} to re-authenticate.`,
       );
+    } else {
+      // Only a 401 means the key was rejected. A 5xx or 429 says nothing
+      // about the key, so don't tell the user to log out.
+      console.log(
+        `  ${c.yellow}Could not verify the key (platform returned HTTP ${res.status})${c.reset}`,
+      );
+      console.log(`  ${c.dim}Key:    ${masked}${c.reset}`);
+      console.log(`  ${c.dim}Source: ${source}${c.reset}`);
     }
   } catch {
     console.log(

package/bin/claude-picker.js

@@ -0,0 +1,143 @@
+// The env claudeModelPickerEnv sets, described for readers that cannot run it.
+export const CLAUDE_PICKER_ENV_DESCRIPTION = [
+  ...['OPUS', 'SONNET', 'HAIKU', 'FABLE'].flatMap((role, index) => {
+    const alias = role.toLowerCase();
+    return [
+      {
+        name: `ANTHROPIC_DEFAULT_${role}_MODEL`,
+        value: `{catalog[${index}]}`,
+        override: [`ANTHROPIC_DEFAULT_${role}_MODEL`],
+        description: `Model behind the ${alias} alias. Set from the catalog, padded to four entries; a profile or environment value is kept only when it is in the live catalog.`,
+      },
+      {
+        name: `ANTHROPIC_DEFAULT_${role}_MODEL_NAME`,
+        value: `{catalog[${index}]}`,
+        override: [`ANTHROPIC_DEFAULT_${role}_MODEL_NAME`],
+        description: `Picker label for the ${alias} alias.`,
+      },
+      {
+        name: `ANTHROPIC_DEFAULT_${role}_MODEL_DESCRIPTION`,
+        value: `Subconscious model {catalog[${index}]}`,
+        override: [`ANTHROPIC_DEFAULT_${role}_MODEL_DESCRIPTION`],
+        description: `Picker description for the ${alias} alias.`,
+      },
+    ];
+  }),
+  {
+    name: 'ANTHROPIC_CUSTOM_MODEL_OPTION',
+    value: '{catalog[4]}',
+    description:
+      'Fifth picker entry, with _NAME and _DESCRIPTION. Only when the catalog has five or more models.',
+  },
+  {
+    name: 'SUBC_CLAUDE_SETTINGS',
+    value: '{claudeSettings}',
+    description: 'Picker settings JSON passed to --settings.',
+  },
+];
+
+const CLAUDE_MODEL_PICKER_KEYS = [
+  'ANTHROPIC_DEFAULT_OPUS_MODEL',
+  'ANTHROPIC_DEFAULT_OPUS_MODEL_NAME',
+  'ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION',
+  'ANTHROPIC_DEFAULT_SONNET_MODEL',
+  'ANTHROPIC_DEFAULT_SONNET_MODEL_NAME',
+  'ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION',
+  'ANTHROPIC_DEFAULT_HAIKU_MODEL',
+  'ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME',
+  'ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION',
+  'ANTHROPIC_DEFAULT_FABLE_MODEL',
+  'ANTHROPIC_DEFAULT_FABLE_MODEL_NAME',
+  'ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION',
+  'ANTHROPIC_CUSTOM_MODEL_OPTION',
+  'ANTHROPIC_CUSTOM_MODEL_OPTION_NAME',
+  'ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION',
+];
+
+const CLAUDE_MODEL_PICKER_ID_KEYS = [
+  'ANTHROPIC_DEFAULT_OPUS_MODEL',
+  'ANTHROPIC_DEFAULT_SONNET_MODEL',
+  'ANTHROPIC_DEFAULT_HAIKU_MODEL',
+  'ANTHROPIC_DEFAULT_FABLE_MODEL',
+  'ANTHROPIC_CUSTOM_MODEL_OPTION',
+];
+
+function uniqueCatalogModels(models, fallbackModel) {
+  const unique = [];
+  for (const model of models) {
+    if (model && !unique.includes(model)) unique.push(model);
+  }
+  if (unique.length === 0 && fallbackModel) unique.push(fallbackModel);
+  return unique;
+}
+
+export function claudePickerSettings(models, fallbackModel) {
+  const unique = uniqueCatalogModels(models, fallbackModel);
+  return {
+    availableModels: unique,
+    modelPicker: {
+      replaceBuiltInOptions: true,
+      options: unique.map((model) => ({
+        model,
+        label: model,
+        description: `Subconscious model ${model}`,
+      })),
+    },
+  };
+}
+
+export function claudeModelPickerEnv(model, models) {
+  // Only the live catalog belongs in Claude's picker. Packaged registry slots
+  // (Haiku → DeepSeek, etc.) must not be unioned back in — that advertised
+  // models the key cannot call.
+  //
+  // Pad through Fable so the built-in `fable` alias cannot resolve to Anthropic
+  // Fable 5. The /model menu itself is replaced via claudePickerSettings.
+  const pickerModels = uniqueCatalogModels(models, model);
+  while (pickerModels.length < 4)
+    pickerModels.push(pickerModels.at(-1) || model);
+
+  const roles = ['OPUS', 'SONNET', 'HAIKU', 'FABLE'];
+  const env = {};
+  for (let index = 0; index < roles.length; index++) {
+    const role = roles[index];
+    const model = pickerModels[index];
+    if (!model) continue;
+    env[`ANTHROPIC_DEFAULT_${role}_MODEL`] = model;
+    env[`ANTHROPIC_DEFAULT_${role}_MODEL_NAME`] = model;
+    env[`ANTHROPIC_DEFAULT_${role}_MODEL_DESCRIPTION`] =
+      `Subconscious model ${model}`;
+  }
+  const customModel = pickerModels[4];
+  if (customModel) {
+    env.ANTHROPIC_CUSTOM_MODEL_OPTION = customModel;
+    env.ANTHROPIC_CUSTOM_MODEL_OPTION_NAME = customModel;
+    env.ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION = `Subconscious model ${customModel}`;
+  }
+  return Object.fromEntries(
+    CLAUDE_MODEL_PICKER_KEYS.map((key) => [key, env[key]]).filter(
+      ([, value]) => value,
+    ),
+  );
+}
+
+export function applyClaudePickerCatalog(env, picker, models) {
+  if (Object.keys(picker).length === 0) return env;
+  const allowed = new Set(models);
+
+  for (const key of CLAUDE_MODEL_PICKER_KEYS) {
+    if (!picker[key]) {
+      delete env[key];
+    }
+  }
+
+  for (const key of CLAUDE_MODEL_PICKER_ID_KEYS) {
+    if (!picker[key] || !env[key] || allowed.has(env[key])) continue;
+    env[key] = picker[key];
+    const nameKey = `${key}_NAME`;
+    const descriptionKey = `${key}_DESCRIPTION`;
+    if (picker[nameKey]) env[nameKey] = picker[nameKey];
+    if (picker[descriptionKey]) env[descriptionKey] = picker[descriptionKey];
+  }
+  return env;
+}

package/bin/cli.js

@@ -14,6 +14,7 @@ import {
   agentCommandName,
   agentList,
   isAgentHelpRequest,
+  isHeadlessRequest,
   parseAgentAction,
   resolveAgent,
   runAgent,
@@ -28,6 +29,11 @@ import {
 import { renderBanner } from './branding.js';
 import { c } from './colors.js';
 import { feedbackCommand, printFeedbackHelp } from './feedback.js';
+import {
+  harnessManifestCommand,
+  printHarnessManifestHelp,
+} from './harness-manifest.js';
+import { headlessPromptIndex } from './headless-args.js';
 import { resolveModelCatalog } from './models.js';
 import {
   configCommand,
@@ -86,6 +92,7 @@ function printHelp() {
 
   ${c.bold}Coding agents${c.reset}
 ${agents}
+    ${c.cyan}harness-manifest${c.reset}  Print how each agent is installed and launched (JSON)
 
   ${c.bold}Options${c.reset}
     ${c.dim}--model <id>${c.reset}   Model to use (profile MODEL, or first live catalog model if UNSET)
@@ -111,6 +118,8 @@ ${agents}
     ${c.dim}$${c.reset} subc cursor install
     ${c.dim}$${c.reset} subc cursor uninstall
     ${c.dim}$${c.reset} subc pi install
+    ${c.dim}$${c.reset} subc harness-manifest --json
+    ${c.dim}$${c.reset} subc codex headless "fix the failing test"
     ${c.dim}$${c.reset} subc -p staging codex
 
   ${c.dim}Use subc <command> help for command-specific usage.${c.reset}
@@ -150,7 +159,8 @@ Usage:
   subc upgrade --latest
   subc upgrade help
 
-Upgrade subconscious-cli to the latest published version.
+Upgrade subconscious-cli to the latest published version, the same way it
+was installed: npm (or pnpm, yarn, bun), or the curl installer.
 
   subc upgrade           Prompt "Do you want to upgrade?" then install @latest
   subc upgrade --latest  Skip the prompt and install @latest
@@ -245,12 +255,45 @@ const authCommands = {
   whoami: whoamiCommand,
 };
 
+/**
+ * Position of the headless prompt in the full argv, or -1. It is decided on
+ * the words left once profile flags are removed, which is what the agent
+ * launcher sees, so both agree on whether the run is headless.
+ */
+function headlessPromptPosition(argv) {
+  const kept = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const afterCommand = kept.slice(1).map((index) => argv[index]);
+    if (
+      kept.length > 0 &&
+      headlessPromptIndex(afterCommand) === afterCommand.length
+    ) {
+      return i;
+    }
+    if (arg === '--') return -1;
+    if (arg === '--profile' || arg === '-p') {
+      i++;
+      continue;
+    }
+    if (arg.startsWith('--profile=')) continue;
+    kept.push(i);
+  }
+  return -1;
+}
+
 function extractProfile(argv) {
   let profileName = process.env.SUBC_PROFILE?.trim() || DEFAULT_PROFILE;
   let profileExplicit = false;
   const args = [];
+  // The headless prompt is opaque, even when it looks like --profile.
+  const promptIndex = headlessPromptPosition(argv);
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
+    if (i === promptIndex) {
+      args.push(arg);
+      continue;
+    }
     if (arg === '--') {
       args.push(...argv.slice(i));
       break;
@@ -296,15 +339,32 @@ async function main() {
     return;
   }
 
+  // Machine-readable output: skip the update check so nothing else reaches
+  // stdout and no npm request is made.
+  if (command === 'harness-manifest') {
+    if (isHelpArg(args[1])) {
+      printHarnessManifestHelp();
+      return;
+    }
+    harnessManifestCommand(args.slice(1));
+    return;
+  }
+
   const launchTui =
     !command &&
     process.stdin.isTTY === true &&
     process.stdout.isTTY === true &&
     process.env.TERM !== 'dumb';
 
+  // Headless runs are scripted: no npm request and no update prompt.
+  const headlessAgent = resolveAgent(command);
+  const headless = Boolean(
+    headlessAgent && isHeadlessRequest(headlessAgent, args.slice(1)),
+  );
+
   // Explicit commands can wait on npm. The TUI opens immediately and prompts
   // only after a newer version is found.
-  if (!launchTui) {
+  if (!launchTui && !headless) {
     const update = await showUpdateNotice();
     if (update?.action === 'updated' || update?.action === 'cancel') return;
   }

package/bin/clipboard-image.js

@@ -58,7 +58,9 @@ async function readDarwinClipboard() {
 async function readLinuxClipboard() {
   const commands = [
     ['wl-paste', ['--type', 'image/png']],
+    ['wl-paste', ['--type', 'image/jpeg']],
     ['xclip', ['-selection', 'clipboard', '-t', 'image/png', '-o']],
+    ['xclip', ['-selection', 'clipboard', '-t', 'image/jpeg', '-o']],
   ];
   for (const [command, args] of commands) {
     try {

package/bin/feedback.js

@@ -17,6 +17,17 @@ import { DEFAULT_PROFILE } from './profiles.js';
 export const FEEDBACK_API_PATH = '/api/cli/feedback';
 export const SUPPORT_EMAIL = 'support@subconscious.dev';
 
+function feedbackOptionValue(argv, index) {
+  const value = argv[index + 1];
+  if (
+    value === undefined ||
+    /^(?:--[A-Za-z][\w-]*|-[A-Za-z])(?:=|$)/.test(value)
+  ) {
+    throw new Error(`${argv[index]} requires a value`);
+  }
+  return value;
+}
+
 /**
  * Parses feedback command arguments. Shared with tests.
  *
@@ -31,15 +42,15 @@ export function parseFeedbackArgs(argv = []) {
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === '-s' || arg === '--subject') {
-      subject = argv[++i] ?? '';
+      subject = feedbackOptionValue(argv, i++);
     } else if (arg.startsWith('--subject=')) {
       subject = arg.slice('--subject='.length);
     } else if (arg === '-m' || arg === '--message') {
-      message = argv[++i] ?? '';
+      message = feedbackOptionValue(argv, i++);
     } else if (arg.startsWith('--message=')) {
       message = arg.slice('--message='.length);
     } else if (arg === '--image') {
-      images.push(argv[++i] ?? '');
+      images.push(feedbackOptionValue(argv, i++));
     } else if (arg.startsWith('--image=')) {
       images.push(arg.slice('--image='.length));
     } else if (arg !== '') {

package/bin/harness-manifest.js

@@ -0,0 +1,286 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import {
+  AGENTS,
+  agentBinary,
+  agentCommandName,
+  agentInputs,
+  installCommands,
+  RUNBOOK_DIR,
+  resolveRefs,
+  staticLookup,
+} from './agent-data.js';
+import { RUNBOOK_ENV_DESCRIPTION } from './agents.js';
+import { CLAUDE_PICKER_ENV_DESCRIPTION } from './claude-picker.js';
+import { c } from './colors.js';
+import { buildOpenCodeConfig } from './opencode-provider.js';
+
+// Bump on any change that can break a reader: a renamed or removed field, or a
+// changed meaning. Adding a field does not need a bump.
+export const HARNESS_MANIFEST_SCHEMA_VERSION = 1;
+
+export const MANIFEST_TOKENS = {
+  '{baseUrl}': 'Gateway origin, without a trailing slash.',
+  '{baseUrlV1}': 'Gateway origin followed by /v1.',
+  '{apiKey}': "The agent's API key input when set, otherwise API_KEY.",
+  '{model}': 'Launch model ID.',
+  '${NAME}':
+    'Value of env var NAME at launch. The manifest replaces it with the default when NAME is an input or env entry; a reference followed by / drops trailing slashes.',
+  '{catalog}': 'Every live catalog model ID, newline-separated.',
+  '{catalog[N]}':
+    'Catalog model at index N, clamped to the last entry; {model} when the catalog is empty.',
+  '{args}': 'Arguments passed through from subc, after its own flags.',
+  '{config}':
+    'config_flag NAME=VALUE for each cli-config entry whose condition holds.',
+  '{prompt}': 'The task given to subc <agent> headless PROMPT.',
+  '{sessionId}': 'A local session ID, for launch.resume.',
+  '{sessionFile}': "A local session's file, or its ID when it has none.",
+  '{tempFile}':
+    'Temporary file the runbook writes; the matching config entry says whether it is removed.',
+  '{tmp}': 'System temporary directory.',
+  '{opencodeConfig}':
+    'The OpenCode config document shown in the env-json config entry.',
+  '{claudeSettings}': 'JSON document described by the --settings config entry.',
+  '{target}':
+    'Release target triple, one of install.targets or install.windows_targets.',
+  '{binDir}': "Directory the agent's binary was found in.",
+  '{PATH}': "The caller's PATH.",
+  '<install dirs>': 'Common install directories subc adds to PATH.',
+  '<agent key>': 'The agent-specific API key input, for example CODEX_API_KEY.',
+  '<id>': 'Any model ID in the catalog; the field repeats for each model.',
+  'models[]': 'Every element of the models array.',
+  '<runbook>': 'Absolute path of the installed bin/runbook directory.',
+  '<VS Code user dir>':
+    'The VS Code user settings directory, for example ~/Library/Application Support/Code/User.',
+};
+
+const PACKAGE_URL = new URL('../package.json', import.meta.url);
+
+function conditionText(when) {
+  return Object.entries(when)
+    .map(([name, test]) =>
+      test === 'set'
+        ? `${name} non-empty`
+        : test === 'empty'
+          ? `${name} empty`
+          : `${name} != ${test.not}`,
+    )
+    .join(' and ');
+}
+
+/** The OpenCode config with placeholders, built by the launch code itself. */
+function openCodeConfigDocument(lookup) {
+  const document = buildOpenCodeConfig({
+    baseUrl: '{baseUrl}',
+    model: '{model}',
+    modelIds: ['<id>'],
+    context: lookup('OPENCODE_CONTEXT_LIMIT'),
+    output: lookup('OPENCODE_OUTPUT_LIMIT'),
+  });
+  // The manifest is the same on every platform, so a Windows path keeps `/`.
+  const portable = (file) =>
+    file.startsWith(RUNBOOK_DIR)
+      ? `<runbook>/${path.relative(RUNBOOK_DIR, file).split(path.sep).join('/')}`
+      : file;
+  return { ...document, plugin: document.plugin.map(portable) };
+}
+
+function resolver(agent) {
+  const lookup = staticLookup(agent);
+  return (value) =>
+    value === '{opencodeConfig}'
+      ? openCodeConfigDocument(lookup)
+      : resolveRefs(value, lookup);
+}
+
+function inputEntry(input, resolve) {
+  return input.default === undefined
+    ? input
+    : { ...input, default: resolve(input.default) };
+}
+
+function exportedEnv(input, resolve) {
+  return {
+    name: input.name,
+    value: String(resolve(input.default)),
+    override: [input.name, ...(input.aliases || [])],
+    description: input.description,
+  };
+}
+
+function envEntries(agent, resolve) {
+  const inputs = agentInputs(agent).filter((input) => input.export);
+  const own = agent.env.map((entry) => ({
+    ...entry,
+    value:
+      entry.value === '{opencodeConfig}'
+        ? entry.value
+        : String(resolve(entry.value)),
+    override: entry.override || [],
+  }));
+  const launcher =
+    agent.id === 'claude-code' ? CLAUDE_PICKER_ENV_DESCRIPTION : [];
+  return [
+    ...inputs.map((input) => exportedEnv(input, resolve)),
+    ...own,
+    ...launcher,
+  ];
+}
+
+function inputBehindRef(agent, value) {
+  const name = /^\$\{([A-Z_][A-Z0-9_]*)\}$/.exec(value ?? '')?.[1];
+  return name && agentInputs(agent).find((input) => input.name === name);
+}
+
+/** Where a value that reads an input can be changed: its env names and flag. */
+function overrideFor(input) {
+  return [
+    input.name,
+    ...(input.aliases || []),
+    ...(input.flag ? [input.flag] : []),
+  ];
+}
+
+function configEntry(agent, entry, resolve) {
+  const { when, ...rest } = entry;
+  const out = { ...rest };
+  if ('value' in entry) out.value = resolve(entry.value);
+  const input = inputBehindRef(agent, entry.value);
+  if (input) out.override = overrideFor(input);
+  if (when) out.condition = conditionText(when);
+  return out;
+}
+
+/** A knob that reads an input says where the value comes from and its bounds. */
+function knob(agent, setting, resolve) {
+  const input = inputBehindRef(agent, setting.value);
+  const value = resolve(setting.value);
+  const out = {
+    ...setting,
+    value: setting.kind === 'env' ? String(value) : value,
+  };
+  if (input && !setting.override) out.override = overrideFor(input);
+  if (input && setting.range)
+    out.range = { min: input.min, max: input.max, ...setting.range };
+  return out;
+}
+
+function capabilities(agent, resolve) {
+  const { compaction, ...rest } = agent.capabilities;
+  const knobs = Object.fromEntries(
+    ['on', 'off', 'threshold'].map((mode) => [
+      mode,
+      knob(agent, compaction[mode], resolve),
+    ]),
+  );
+  return { ...resolve(rest), compaction: { ...compaction, ...knobs } };
+}
+
+function harnessEntry(agent) {
+  const resolve = resolver(agent);
+  const { runbook } = agent;
+  const script = (name) => (name ? `${agent.id}/${name}` : null);
+  return {
+    id: agent.id,
+    name: agent.name,
+    command: `subc ${agentCommandName(agent)}`,
+    aliases: agent.aliases,
+    mode: runbook.mode,
+    protocol: agent.protocol,
+    runbook: {
+      dir: agent.id,
+      launch: script(runbook.script),
+      setup: script(runbook.setup_script),
+      setup_actions: runbook.setup_actions || [],
+    },
+    binary: agentBinary(agent),
+    install: { ...agent.install, commands: installCommands(agent) },
+    prerequisites: agent.prerequisites,
+    launch: agent.launch ?? null,
+    inputs: agentInputs(agent).map((input) => inputEntry(input, resolve)),
+    env: envEntries(agent, resolve),
+    config: agent.config.map((entry) => configEntry(agent, entry, resolve)),
+    capabilities: capabilities(agent, resolve),
+  };
+}
+
+/** The manifest, computed from the agent files this subc ships. */
+export function loadHarnessManifest() {
+  return {
+    schema_version: HARNESS_MANIFEST_SCHEMA_VERSION,
+    cli_version: JSON.parse(readFileSync(PACKAGE_URL, 'utf-8')).version,
+    cli_package: 'subconscious-cli',
+    tokens: MANIFEST_TOKENS,
+    runbook_env: RUNBOOK_ENV_DESCRIPTION,
+    harnesses: Object.fromEntries(
+      AGENTS.map((agent) => [agent.id, harnessEntry(agent)]),
+    ),
+  };
+}
+
+export function printHarnessManifestHelp() {
+  console.log(`
+Usage:
+  subc harness-manifest [--json]
+  subc harness-manifest help
+
+Print how this subc version installs, configures, and launches each coding
+harness: install source, binary, env vars, config files, compaction knobs,
+MCP, headers, and hooks.
+
+  --json   Print the full manifest as JSON. This is the default when stdout
+           is not a terminal; in a terminal, a summary table is printed.
+`);
+}
+
+function compactionSummary(compaction) {
+  const supported = ['on', 'off', 'threshold'].filter(
+    (mode) => compaction[mode]?.set_by_subc,
+  );
+  return supported.length ? supported.join(',') : '-';
+}
+
+function tableRows(manifest) {
+  return Object.values(manifest.harnesses).map((harness) => [
+    harness.id,
+    harness.binary || '-',
+    harness.install.package || harness.install.repository || '-',
+    String(harness.env.length),
+    compactionSummary(harness.capabilities.compaction),
+    String(harness.capabilities.hooks.length),
+  ]);
+}
+
+function printTable(manifest) {
+  const header = ['harness', 'binary', 'install', 'env', 'compaction', 'hooks'];
+  const rows = tableRows(manifest);
+  const widths = header.map((title, index) =>
+    Math.max(title.length, ...rows.map((row) => row[index].length)),
+  );
+  const line = (cells) =>
+    `  ${cells.map((cell, index) => cell.padEnd(widths[index])).join('  ')}`;
+  console.log(
+    `\n  ${c.bold}Harness manifest${c.reset} ${c.dim}schema ${manifest.schema_version}, subc ${manifest.cli_version}${c.reset}\n`,
+  );
+  console.log(`${c.dim}${line(header)}${c.reset}`);
+  for (const row of rows) console.log(line(row));
+  console.log(
+    `\n  ${c.dim}compaction lists the modes subc sets. Use --json for every field.${c.reset}\n`,
+  );
+}
+
+export function harnessManifestCommand(args = [], options = {}) {
+  const unknown = args.filter((arg) => arg !== '--json');
+  if (unknown.length) {
+    throw new Error(
+      `Unknown argument: ${unknown[0]}. Try subc harness-manifest help.`,
+    );
+  }
+  const isTTY = options.isTTY ?? process.stdout.isTTY === true;
+  const manifest = loadHarnessManifest();
+  if (args.includes('--json') || !isTTY) {
+    process.stdout.write(`${JSON.stringify(manifest, null, 2)}\n`);
+    return;
+  }
+  printTable(manifest);
+}

package/bin/headless-args.js

@@ -0,0 +1,35 @@
+const SUBC_PROFILE_FLAGS = new Set(['-p', '--profile']);
+const SUBC_INLINE_FLAGS = ['--model=', '--profile='];
+
+/** Whether `--model` consumes the word after it. An empty word is a value. */
+export function takesModelValue(value) {
+  return value !== undefined && !value.startsWith('-');
+}
+
+/**
+ * Index of the headless prompt when `argv` (the words after the agent name)
+ * asks for a headless run, otherwise -1. Only subc's own flags may come
+ * before "headless"; later on it is an ordinary agent argument.
+ */
+export function headlessPromptIndex(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (SUBC_PROFILE_FLAGS.has(arg)) {
+      i++;
+      continue;
+    }
+    if (arg === '--model') {
+      if (takesModelValue(argv[i + 1])) i++;
+      continue;
+    }
+    if (SUBC_INLINE_FLAGS.some((prefix) => arg.startsWith(prefix))) continue;
+    return arg === 'headless' ? i + 1 : -1;
+  }
+  return -1;
+}
+
+/** Index of the first "--" separator; a headless prompt of "--" is not one. */
+export function separatorIndex(argv) {
+  const prompt = headlessPromptIndex(argv);
+  return argv.findIndex((arg, index) => arg === '--' && index !== prompt);
+}

package/bin/launch-values.js

@@ -0,0 +1,25 @@
+import { DEFAULTS, PACKAGED_MODELS } from './agent-data.js';
+
+const MODEL_ID = /^[-A-Za-z0-9._:/+]+$/;
+
+/** The launch model first, then the catalog, deduplicated and validated. */
+export function modelIds(env) {
+  const catalog = (
+    env.SUBCONSCIOUS_MODELS?.trim() || PACKAGED_MODELS.join('\n')
+  ).split(/\r?\n/);
+  const models = [
+    ...new Set([env.MODEL?.trim() || DEFAULTS.model, ...catalog]),
+  ].filter(Boolean);
+  for (const model of models)
+    if (!MODEL_ID.test(model)) throw new Error(`Invalid model id: ${model}`);
+  return models;
+}
+
+export function positiveInteger(input, name) {
+  if (
+    !/^[1-9][0-9]*$/.test(String(input)) ||
+    !Number.isSafeInteger(Number(input))
+  )
+    throw new Error(`${name} must be a positive integer`);
+  return Number(input);
+}