@pome-sh/cli 0.27.0 → 0.29.0

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
   "package": "pome-sh",
-  "version": "0.27.0",
-  "git_sha": "112e066d008ebf62c5dc1176f39c87798d1c299b",
-  "build_time": "2026-08-26T18:46:48.367Z"
+  "version": "0.29.0",
+  "git_sha": "b065b0336a80c35d63c53bed262be6b037bfec76",
+  "build_time": "2026-08-26T21:23:55.631Z"
 }

package/dist/{checks-QM7QOJ6U.js → checks-JR4OEKZM.js}

@@ -1,6 +1,6 @@
-import { findManifestPath, readManifest } from './chunk-CXGMLUZ4.js';
+import { findManifestPath, readManifest } from './chunk-VO2XUPZC.js';
 import { getAvailablePort } from './chunk-XDU6TD4O.js';
-import './chunk-BZO3YCJS.js';
+import './chunk-E7WJ3SRP.js';
 import { buildEgressAllowlist } from './chunk-CBFKZZBR.js';
 import './chunk-6KJC4BTO.js';
 import './chunk-SG6ZTIMT.js';
@@ -183,7 +183,7 @@ async function checkTwinReachable(_configDir) {
   });
   let harness;
   try {
-    const { bootTwin } = await import('./twinHarness-YOVJR72F.js');
+    const { bootTwin } = await import('./twinHarness-CUVRO5IV.js');
     harness = await bootTwin({
       twin: "github",
       seedState: void 0,

package/dist/chunk-B7PA7UDX.js

@@ -0,0 +1,105 @@
+import { isTwinName, TWIN_REGISTRY, TWIN_NAMES } from './chunk-SRG22BIH.js';
+import { readFileSync } from 'node:fs';
+import { parse } from 'yaml';
+
+function readSeedFileText(path, flag = "--seed") {
+  try {
+    return readFileSync(path, "utf8");
+  } catch (err) {
+    throw new Error(`${flag}: cannot read ${path}: ${err.message}`);
+  }
+}
+function parseSeedFileText(raw, origin) {
+  let parsed;
+  try {
+    parsed = parse(raw);
+  } catch (err) {
+    throw new Error(`${origin} is not valid JSON or YAML: ${err.message}`);
+  }
+  if (Array.isArray(parsed)) {
+    throw new Error(`${origin} is not a seed file: its top level is an array, not an object.`);
+  }
+  if (parsed === null || typeof parsed !== "object") {
+    throw new Error(
+      `${origin} is not a seed file: its top level is ${parsed === null ? "null" : typeof parsed}, not an object.`
+    );
+  }
+  const { _meta, ...rest } = parsed;
+  const keys = Object.keys(rest);
+  const twinKeys = keys.filter((key) => isTwinName(key));
+  if (twinKeys.length === 0) return { shape: "flat", seed: rest };
+  if (twinKeys.length !== keys.length) {
+    const others = keys.filter((key) => !isTwinName(key));
+    throw new Error(
+      `${origin} mixes twin ids (${twinKeys.join(", ")}) with other keys (${others.join(", ")}). A seed file is either one twin's flat seed or a per-twin envelope { <twin>: <seed> }, not both.`
+    );
+  }
+  return { shape: "envelope", byTwin: rest };
+}
+function twinsNamedBy(file) {
+  if (file.shape === "flat") return [];
+  return Object.keys(file.byTwin).filter((key) => isTwinName(key));
+}
+function soleTwinOf(file) {
+  const named = twinsNamedBy(file);
+  return named.length === 1 ? named[0] : void 0;
+}
+async function seedFieldsFor(twin) {
+  return TWIN_REGISTRY[twin].seedFields();
+}
+async function seedForTwin(file, twin, origin, opts = {}) {
+  if (file.shape === "flat") return parseWith(twin, file.seed, origin, file);
+  assertOnlyAsked(file, opts.asked, origin);
+  const named = twinsNamedBy(file);
+  if (!(twin in file.byTwin)) {
+    throw new Error(
+      `${origin} declares no ${twin} seed (it names ${named.join(", ")}). Add a "${twin}" key, or start the twin it names.`
+    );
+  }
+  return parseWith(twin, file.byTwin[twin], `${origin} ("${twin}")`, file);
+}
+async function seedsForTwins(file, twins, origin) {
+  if (file.shape === "flat") {
+    if (twins.length !== 1) {
+      throw new Error(
+        `${origin} is a flat seed and this sandbox has ${twins.length} twins (${twins.join(", ")}), so nothing says which one it is for. Wrap it in a per-twin envelope: { "${twins[0] ?? "<twin>"}": { \u2026 } }.`
+      );
+    }
+    return { [twins[0]]: await parseWith(twins[0], file.seed, origin, file) };
+  }
+  assertOnlyAsked(file, twins, origin);
+  const out = {};
+  for (const twin of twins) {
+    if (twin in file.byTwin) {
+      out[twin] = await parseWith(twin, file.byTwin[twin], `${origin} ("${twin}")`, file);
+    }
+  }
+  return out;
+}
+function assertOnlyAsked(file, asked, origin) {
+  if (asked === void 0 || file.shape !== "envelope") return;
+  const extras = twinsNamedBy(file).filter((twin) => !asked.includes(twin));
+  if (extras.length === 0) return;
+  throw new Error(
+    `${origin} names ${extras.join(", ")}, which this command was not asked for (asked: ${asked.length ? asked.join(", ") : "none"}). Add --twin for each, or remove them from the file.`
+  );
+}
+async function parseWith(twin, seed, where, file) {
+  try {
+    return await TWIN_REGISTRY[twin].parseSeed(seed);
+  } catch (err) {
+    const hint = file.shape === "flat" ? await notSeedFieldsHint(twin, file.seed) : "";
+    throw new Error(`${where} is not a seed this twin can boot: ${err.message}${hint}`);
+  }
+}
+async function notSeedFieldsHint(twin, seed) {
+  if (seed === null || typeof seed !== "object" || Array.isArray(seed)) return "";
+  const keys = Object.keys(seed);
+  if (keys.length === 0) return "";
+  const fields = new Set(await seedFieldsFor(twin));
+  if (keys.some((key) => fields.has(key))) return "";
+  return `
+  None of its top-level keys (${keys.join(", ")}) is a field of the ${twin} seed. If this file is a per-twin envelope, its keys must be twin ids: ${TWIN_NAMES.join(", ")}.`;
+}
+
+export { parseSeedFileText, readSeedFileText, seedForTwin, seedsForTwins, soleTwinOf, twinsNamedBy };

package/dist/{chunk-BZO3YCJS.js → chunk-E7WJ3SRP.js}

@@ -91,8 +91,40 @@ var baseCriterionResultSchema = z.object({
   passed: z.boolean(),
   skipped: z.boolean(),
   // true if [code] fell back to [model] but the judge was unreachable, etc.
-  reason: z.string()
+  reason: z.string(),
   // human-readable evidence
+  // Why this row is out of the denominator, when `skipped` alone is too coarse.
+  // The two values that carry meaning here are `ADVISORY_SCORE_STATE` and
+  // `ABSTAINED_SCORE_STATE` (`@pome-sh/wire/run-completeness`), which the
+  // narrator stamps on a `[model]` row it read but had no authority to score.
+  //
+  // NOT NAMED `outcome`: `hosted/evalResultView.ts`'s display model has
+  // reserved that key on this same object for a disjoint vocabulary
+  // (`passed | failed | skipped | errored`) since long before the narrator, and
+  // reserved it for the CLOUD to fill. A cloud writing `advisory` into it would
+  // hand `outcomeOf` a value outside its own union and render an advisory row
+  // with the skipped glyph.
+  //
+  // ON THE BASE AND NOT ON ONE ARM, for the mirror image of the reason the arm
+  // order below is what it is: an advisory row carries no `confidence` /
+  // `judge_model`, so it fails the probabilistic arm and lands on the
+  // DETERMINISTIC one — whose `.extend({})` is a plain `z.object` and would
+  // strip an unknown key. Declared on one arm, the state would be discarded
+  // before any consumer could read it, and the run would keep reading
+  // INCOMPLETE with the exemption sitting there correct and dead.
+  //
+  // `z.string()` AND NOT THE CLOSED ENUM pome-cloud declares for the same
+  // field, because the two sides of it have opposite jobs. pome-cloud PRODUCES
+  // it and validates what it serves; the CLI CONSUMES it, and
+  // `finalizeResponseSchema` is deliberately a tolerant reader (its own comment
+  // says so: cloud may emit additive keys "that older/newer CLIs strip rather
+  // than reject"). A closed enum here would turn a cloud that adds a third
+  // score state into a hard parse failure of the ENTIRE /finalize response —
+  // an unreadable run instead of an unrecognised field. The closed vocabulary
+  // is applied by the PREDICATE that reads it (`isNarrated`), exactly as
+  // `reason` is a plain string and `PRE_SATISFIED_REASON` is a comparison, so
+  // an unrecognised spelling is not exempted from anything.
+  score_state: z.string().optional()
 });
 var deterministicCriterionResultSchema = baseCriterionResultSchema.extend({
   // [code] adds nothing further; criterion.type === "code" identifies it.
@@ -704,6 +736,9 @@ z.record(
   z.string(),
   z.record(z.string(), z.unknown())
 );
+function isMultiTwinSeedEnvelope(twins) {
+  return twins.length > 1;
+}
 var taskClassSchema = z.enum(["conformance", "restraint", "adversarial"]);
 var taskConfigSchema = z.object({
   twins: z.array(z.string()).default(["github"]),
@@ -1232,4 +1267,4 @@ function exitCodeFor(err) {
   return 2;
 }
 
-export { HostedAuthError, HostedDiscardRefusedError, HostedOrchError, HostedQuotaError, HostedTrialError, HostedUsageError, MOUNTED_TWINS, SLUG_RE, agentResponseSchema, createEvalSessionResponseSchema, createSessionResponseSchema, criterionSchema, deriveAgentSlug, exitCodeFor, finalizeResponseSchema, manifestSchema, sessionPublicSchema, submitResultResponseSchema };
+export { HostedAuthError, HostedDiscardRefusedError, HostedOrchError, HostedQuotaError, HostedTrialError, HostedUsageError, MOUNTED_TWINS, SLUG_RE, agentResponseSchema, createEvalSessionResponseSchema, createSessionResponseSchema, criterionSchema, deriveAgentSlug, exitCodeFor, finalizeResponseSchema, isMultiTwinSeedEnvelope, manifestSchema, sessionPublicSchema, submitResultResponseSchema };

package/dist/{chunk-N74LP4QH.js → chunk-IYMDPMMZ.js}

@@ -1,5 +1,5 @@
-import { parseTaskFile, seedStateForTwin, runAgentCommand, writeRunArtifactsCore } from './chunk-CTA54N4K.js';
-import { createRecorder, bootTwin } from './chunk-IK2F7ZA3.js';
+import { parseTaskFile, seedStateForTwin, runAgentCommand, writeRunArtifactsCore } from './chunk-XAQGX7K2.js';
+import { createRecorder, bootTwin } from './chunk-S6JLWI4S.js';
 import { getAvailablePort } from './chunk-XDU6TD4O.js';
 import { buildEgressAllowlist, readBlockedEgress } from './chunk-CBFKZZBR.js';
 import { eventSchema } from './chunk-6KJC4BTO.js';

package/dist/{chunk-MQE6DKIK.js → chunk-MRCYOSBM.js}

@@ -1,6 +1,7 @@
-import { createHostedClient, perTwinReturnedByCloud, parseTaskFile, runAgentCommand, writeRunArtifactsCore, toTwinHttpEvent, redactJsonl, uploadRunBlobs, scoreFromFinalizeResponse, scoreStatus, evaluationCounts } from './chunk-CTA54N4K.js';
-import { readManifest, normalizeManifestTwins } from './chunk-CXGMLUZ4.js';
-import { MOUNTED_TWINS, HostedAuthError, HostedDiscardRefusedError, HostedQuotaError, HostedOrchError, HostedTrialError, agentResponseSchema } from './chunk-BZO3YCJS.js';
+import { createHostedClient, perTwinReturnedByCloud, parseTaskFile, runAgentCommand, writeRunArtifactsCore, toTwinHttpEvent, redactJsonl, uploadRunBlobs, scoreFromFinalizeResponse, scoreStatus, evaluationCounts } from './chunk-XAQGX7K2.js';
+import { readSeedFileText, parseSeedFileText, soleTwinOf, seedsForTwins } from './chunk-B7PA7UDX.js';
+import { readManifest, normalizeManifestTwins } from './chunk-VO2XUPZC.js';
+import { MOUNTED_TWINS, HostedAuthError, HostedDiscardRefusedError, HostedQuotaError, HostedOrchError, HostedTrialError, agentResponseSchema, isMultiTwinSeedEnvelope } from './chunk-E7WJ3SRP.js';
 import { redactSecrets, redactEvent } from './chunk-SG6ZTIMT.js';
 import { randomUUID, createHash } from 'node:crypto';
 import { rm, readFile, stat, mkdir, writeFile, chmod, mkdtemp, readdir, rename } from 'node:fs/promises';
@@ -697,8 +698,22 @@ function normalizeSessionTwins(raw) {
   }
   return deduped;
 }
+async function resolveSessionSeed(seedPath, requestedTwins) {
+  const raw = readSeedFileText(seedPath, "pome sandbox create --seed");
+  const origin = `--seed ${seedPath}`;
+  const file = parseSeedFileText(raw, origin);
+  const twins = normalizeSessionTwins(
+    requestedTwins.length > 0 ? requestedTwins : [soleTwinOf(file) ?? ""].filter(Boolean)
+  );
+  const byTwin = await seedsForTwins(file, twins, origin);
+  return {
+    twins,
+    seed: isMultiTwinSeedEnvelope(twins) ? byTwin : byTwin[twins[0]]
+  };
+}
 async function runSessionCreate(opts) {
-  const twins = normalizeSessionTwins(opts.twins);
+  const resolvedSeed = opts.seedPath === void 0 ? void 0 : await resolveSessionSeed(opts.seedPath, opts.twins);
+  const twins = resolvedSeed?.twins ?? normalizeSessionTwins(opts.twins);
   const creds = await resolveCredentials({ apiBaseUrl: opts.apiBaseUrl });
   const client = createHostedClient({
     baseUrl: creds.apiBaseUrl,
@@ -713,7 +728,8 @@ async function runSessionCreate(opts) {
     taskSource: "# ..\n",
     idempotencyKey: randomUUID(),
     agentId: identity.agentId,
-    agentVersion: identity.agentVersion
+    agentVersion: identity.agentVersion,
+    ...resolvedSeed ? { seed: resolvedSeed.seed } : {}
   });
   if (opts.secretsFile) {
     await writeSecretsFile(opts.secretsFile, formatEnvExport(session, twins));
@@ -736,6 +752,9 @@ async function runSessionCreate(opts) {
   }
   console.error(`Session: ${session.session_id}`);
   console.error(`Expires: ${session.expires_at}`);
+  if (opts.seedPath !== void 0) {
+    console.error(`Seed: ${opts.seedPath} (replaces the default for ${twins.join(", ")}).`);
+  }
   let printedAny = false;
   const mcpFromCloud = perTwinReturnedByCloud(session);
   for (const twin of twins) {

package/dist/{chunk-IK2F7ZA3.js → chunk-S6JLWI4S.js}

@@ -1,4 +1,4 @@
-import { TWIN_NAMES, isTwinName, TWIN_REGISTRY } from './chunk-JE4H5ODK.js';
+import { TWIN_NAMES, isTwinName, TWIN_REGISTRY } from './chunk-SRG22BIH.js';
 import { createFileBackedRecorderStore, createRecorderStore } from './chunk-E665XWYU.js';
 
 // src/recorder/recorder.ts

package/dist/{chunk-JE4H5ODK.js → chunk-SRG22BIH.js}

@@ -30,10 +30,9 @@ var TWIN_REGISTRY = {
     envName: "GITHUB",
     defaultPort: 3333,
     version: package_default.version,
-    // The github twin's own `defaultSeedState()` is applied by `boot` below
-    // when no seed is supplied — the pre-existing standalone behavior.
-    defaultSeed: async () => void 0,
+    defaultSeed: async () => (await import('./seed-BG5HMSBM.js')).defaultSeedState(),
     parseSeed: async (input) => (await import('./seed-BG5HMSBM.js')).parseSeed(input),
+    seedFields: async () => Object.keys((await import('./seed-BG5HMSBM.js')).seedSchema.shape),
     async boot({ seedState, runId, recorder }) {
       const {
         createGitHubCloneApp,
@@ -60,8 +59,9 @@ var TWIN_REGISTRY = {
     envName: "SLACK",
     defaultPort: 3333,
     version: package_default2.version,
-    defaultSeed: async () => (await import('./src-SKCWAMVQ.js')).defaultSeedState(),
+    defaultSeed: async () => (await import('./seed-IIMBJHAJ.js')).defaultSeedState(),
     parseSeed: async (input) => (await import('./seed-IIMBJHAJ.js')).parseSeed(input),
+    seedFields: async () => Object.keys((await import('./seed-IIMBJHAJ.js')).seedSchema.shape),
     async boot({ seedState, runId, recorder }) {
       const { createSlackTwinApp, openSlackTwinDatabase, SlackDomain } = await import('./src-SKCWAMVQ.js');
       const db = openSlackTwinDatabase(":memory:");
@@ -86,8 +86,9 @@ var TWIN_REGISTRY = {
     envName: "STRIPE",
     defaultPort: 3333,
     version: package_default3.version,
-    defaultSeed: async () => (await import('./src-PW7U25ZX.js')).defaultSeed(),
+    defaultSeed: async () => (await import('./seed-YWDTT2WL.js')).defaultSeed(),
     parseSeed: async (input) => (await import('./seed-YWDTT2WL.js')).parseSeed(input),
+    seedFields: async () => Object.keys((await import('./seed-YWDTT2WL.js')).seedSchema.shape),
     async boot({ seedState, runId, recorder, twinBaseUrl }) {
       const stripeTwin = await import('./src-PW7U25ZX.js');
       const { createApp } = await import('./server-DMLORMOV.js');
@@ -131,8 +132,9 @@ var TWIN_REGISTRY = {
     portEnvName: "GMAIL_TWIN_PORT",
     tokenEnvName: "POME_GMAIL_TOKEN",
     version: package_default4.version,
-    defaultSeed: async () => (await import('./src-KSLAF3I4.js')).defaultSeedState(),
+    defaultSeed: async () => (await import('./seed-NR6RUKXV.js')).defaultSeedState(),
     parseSeed: async (input) => (await import('./seed-NR6RUKXV.js')).parseSeed(input),
+    seedFields: async () => Object.keys((await import('./seed-NR6RUKXV.js')).gmailSeedSchema.shape),
     async boot({ seedState, runId, recorder }) {
       const { createGmailTwinApp, GmailDomain, openGmailTwinDatabase, parseSeed } = await import('./src-KSLAF3I4.js');
       const db = openGmailTwinDatabase(":memory:");
@@ -153,8 +155,9 @@ var TWIN_REGISTRY = {
     portEnvName: "LINEAR_TWIN_PORT",
     tokenEnvName: "POME_LINEAR_TOKEN",
     version: package_default5.version,
-    defaultSeed: async () => (await import('./src-JRBHNT4Y.js')).defaultSeedState(),
-    parseSeed: async (input) => (await import('./seed-3ZTWKLBE.js')).parseSeed(input),
+    defaultSeed: async () => (await import('./seed-F7RNI55S.js')).defaultSeedState(),
+    parseSeed: async (input) => (await import('./seed-F7RNI55S.js')).parseSeed(input),
+    seedFields: async () => Object.keys((await import('./seed-F7RNI55S.js')).linearSeedSchema.shape),
     async boot({ seedState, runId, recorder }) {
       const {
         createLinearTwinApp,
@@ -162,7 +165,7 @@ var TWIN_REGISTRY = {
         LinearDomain,
         openLinearTwinDatabase,
         parseSeed
-      } = await import('./src-JRBHNT4Y.js');
+      } = await import('./src-5YCI6VIR.js');
       const db = openLinearTwinDatabase(":memory:");
       const seed = parseSeed(seedState);
       const domain = new LinearDomain(db);

package/dist/{chunk-CXGMLUZ4.js → chunk-VO2XUPZC.js}

@@ -1,4 +1,4 @@
-import { HostedOrchError, manifestSchema, deriveAgentSlug, SLUG_RE } from './chunk-BZO3YCJS.js';
+import { HostedOrchError, manifestSchema, deriveAgentSlug, SLUG_RE } from './chunk-E7WJ3SRP.js';
 import { readFile, writeFile } from 'node:fs/promises';
 import { resolve, join, dirname } from 'node:path';
 import { stringify, parse } from 'yaml';

package/dist/{chunk-CTA54N4K.js → chunk-XAQGX7K2.js}

@@ -1,7 +1,7 @@
 import { gmailSeedSchema, defaultSeedState } from './chunk-3T5XN64P.js';
-import { linearSeedSchema, defaultSeedState as defaultSeedState$1 } from './chunk-G6GOCYIT.js';
-import { isTwinName, TWIN_REGISTRY } from './chunk-JE4H5ODK.js';
-import { criterionSchema, finalizeResponseSchema, HostedDiscardRefusedError, HostedOrchError, HostedAuthError, HostedQuotaError, submitResultResponseSchema, createEvalSessionResponseSchema, createSessionResponseSchema, sessionPublicSchema } from './chunk-BZO3YCJS.js';
+import { linearSeedSchema, defaultSeedState as defaultSeedState$1 } from './chunk-Q5NBPR57.js';
+import { isTwinName, TWIN_REGISTRY } from './chunk-SRG22BIH.js';
+import { criterionSchema, finalizeResponseSchema, HostedDiscardRefusedError, HostedOrchError, HostedAuthError, HostedQuotaError, submitResultResponseSchema, createEvalSessionResponseSchema, createSessionResponseSchema, sessionPublicSchema } from './chunk-E7WJ3SRP.js';
 import { seedSchema, parseSeed, defaultSeedState as defaultSeedState$2 } from './chunk-HJX25USP.js';
 import { toTwinHttpEventRow } from './chunk-E665XWYU.js';
 import { redactEvent, redactSecrets } from './chunk-SG6ZTIMT.js';
@@ -1255,6 +1255,8 @@ function normalizeAgentSdk(value) {
 
 // ../packages/wire/dist/run-completeness.js
 var PRE_SATISFIED_REASON = "already_true_in_seed";
+var ADVISORY_SCORE_STATE = "advisory";
+var ABSTAINED_SCORE_STATE = "abstained";
 
 // src/hosted/evalResultView.ts
 function outcomeOf(result) {
@@ -1265,6 +1267,9 @@ function outcomeOf(result) {
 function isPreSatisfied(result) {
   return result.skipped && result.reason === PRE_SATISFIED_REASON;
 }
+function isNarrated(result) {
+  return result.skipped && (result.score_state === ADVISORY_SCORE_STATE || result.score_state === ABSTAINED_SCORE_STATE);
+}
 function scoreStatus(score, passThreshold) {
   if (!score.evaluated || !score.can_pass) return "incomplete";
   return score.satisfaction >= passThreshold ? "pass" : "fail";
@@ -1296,12 +1301,16 @@ function criteriaWord(n) {
 }
 function evaluationCounts(score) {
   const evaluated = score.total_required;
-  const notEvaluated = score.skipped + score.errored - score.preSatisfied;
+  const exempt = score.preSatisfied + score.advisory + score.abstained;
+  const notEvaluated = score.skipped + score.errored - exempt;
   return {
     evaluated,
     notEvaluated,
     preSatisfied: score.preSatisfied,
-    total: evaluated + notEvaluated + score.preSatisfied
+    // `total` counts every exemption, not just `preSatisfied`, so it still
+    // names every criterion the run recorded — the reason `outcomeOf` keeps
+    // narrator rows inside `skipped` rather than returning their state raw.
+    total: evaluated + notEvaluated + exempt
   };
 }
 function scoreCountsSummary(score) {
@@ -1486,8 +1495,14 @@ function scoreFromFinalizeResponse(finalized) {
   const preSatisfied = results.filter(
     (r) => outcomeOf(r) === "skipped" && isPreSatisfied(r)
   ).length;
+  const advisory = results.filter(
+    (r) => isNarrated(r) && !isPreSatisfied(r) && r.score_state === ADVISORY_SCORE_STATE
+  ).length;
+  const abstained = results.filter(
+    (r) => isNarrated(r) && !isPreSatisfied(r) && r.score_state === ABSTAINED_SCORE_STATE
+  ).length;
   const totalRequired = passed + failed;
-  const unresolvedAbstentions = skipped - preSatisfied + errored;
+  const unresolvedAbstentions = skipped - preSatisfied - advisory - abstained + errored;
   return {
     satisfaction: finalized.score,
     passed,
@@ -1495,6 +1510,8 @@ function scoreFromFinalizeResponse(finalized) {
     skipped,
     errored,
     preSatisfied,
+    advisory,
+    abstained,
     total_required: totalRequired,
     evaluated: hasCriteriaResults ? totalRequired > 0 : true,
     can_pass: hasCriteriaResults ? totalRequired > 0 && unresolvedAbstentions === 0 : true,

package/dist/{runDemo-O67ASC54.js → runDemo-GBPVF5AA.js}

@@ -1,14 +1,14 @@
 import { newGroupId, reassuranceBox, twinReadyLine, trialsHeaderLine, trialLine, summaryLines, evaluatingLine, criterionPhrase } from './chunk-RGZBC7NF.js';
 import { DemoCapacityError, capacityLabel, parseCapacityMarker, capacityKindFrom } from './chunk-ZX4WNSZ5.js';
-import { runTask, demoTaskPath, DEMO_TASK_NAME, DEMO_REPO } from './chunk-N74LP4QH.js';
-import { createHostedClient, parseTaskFile, uploadRunBlobs, scoreFromFinalizeResponse, scoreStatus, outcomeOf } from './chunk-CTA54N4K.js';
+import { runTask, demoTaskPath, DEMO_TASK_NAME, DEMO_REPO } from './chunk-IYMDPMMZ.js';
+import { createHostedClient, parseTaskFile, uploadRunBlobs, scoreFromFinalizeResponse, scoreStatus, outcomeOf } from './chunk-XAQGX7K2.js';
 import './chunk-NW7HGA2K.js';
 import './chunk-3T5XN64P.js';
-import './chunk-G6GOCYIT.js';
-import { bootTwin } from './chunk-IK2F7ZA3.js';
-import './chunk-JE4H5ODK.js';
+import './chunk-Q5NBPR57.js';
+import { bootTwin } from './chunk-S6JLWI4S.js';
+import './chunk-SRG22BIH.js';
 import { getAvailablePort } from './chunk-XDU6TD4O.js';
-import { HostedQuotaError, HostedOrchError } from './chunk-BZO3YCJS.js';
+import { HostedQuotaError, HostedOrchError } from './chunk-E7WJ3SRP.js';
 import './chunk-CBFKZZBR.js';
 import './chunk-HJX25USP.js';
 import './chunk-E665XWYU.js';

package/dist/{runTrialGroup-V3HB57YI.js → runTrialGroup-XEBG225L.js}

@@ -1,12 +1,13 @@
 import { newGroupId, criterionPhrase } from './chunk-RGZBC7NF.js';
-import { runTaskHosted, resolveRunAgentIdentity } from './chunk-MQE6DKIK.js';
-import { createHostedClient, parseTaskFile, outcomeOf } from './chunk-CTA54N4K.js';
+import { runTaskHosted, resolveRunAgentIdentity } from './chunk-MRCYOSBM.js';
+import { createHostedClient, parseTaskFile, outcomeOf } from './chunk-XAQGX7K2.js';
+import './chunk-B7PA7UDX.js';
 import './chunk-NW7HGA2K.js';
 import './chunk-3T5XN64P.js';
-import './chunk-G6GOCYIT.js';
-import './chunk-JE4H5ODK.js';
-import './chunk-CXGMLUZ4.js';
-import { HostedQuotaError, HostedTrialError } from './chunk-BZO3YCJS.js';
+import './chunk-Q5NBPR57.js';
+import './chunk-SRG22BIH.js';
+import './chunk-VO2XUPZC.js';
+import { HostedQuotaError, HostedTrialError } from './chunk-E7WJ3SRP.js';
 import './chunk-HJX25USP.js';
 import './chunk-E665XWYU.js';
 import './chunk-6KJC4BTO.js';

package/dist/{seed-3ZTWKLBE.js → seed-F7RNI55S.js}

@@ -1 +1 @@
-export { defaultSeedState, linearSeedSchema, loadSeedFromEnv, parseSeed } from './chunk-G6GOCYIT.js';
+export { defaultSeedState, linearSeedSchema, loadSeedFromEnv, parseSeed } from './chunk-Q5NBPR57.js';

package/dist/src/cli/main.js

@@ -1,17 +1,18 @@
 #!/usr/bin/env node
-import { DEFAULT_CONTROL_PLANE_URL, DEFAULT_DASHBOARD_URL, clearLocalCredentials, friendlyHostedError, SESSION_TWIN_NAMES, runSessionCreate, runSessionList, runSessionStop, resolveCredentials, runTaskHosted, discoverRunSet, VERDICT_ARTIFACT_VERSION, persistCredentialsAfterLogin, DEFAULT_DOCS_SITE_ORIGIN, resolveSeams, resolveCachedAgentId, readLinkCache, postAgentResolver, writeLinkCache, ensurePomeGitignored } from '../../chunk-MQE6DKIK.js';
-import { assetPath, runTask, resolvePackageRoot, DEMO_TASK_NAME, demoTaskPath } from '../../chunk-N74LP4QH.js';
-import { parseTaskFile, scoreStatus, runScoreLine, readLatestRun, readMetaSummary, outcomeOf, readConfigTwins, scoreCountsSummary, markerFor, criterionMarkerLabel, twinSkipSuffix, readCodeCriteria, createHostedClient, toTwinHttpEvent, redactJsonl, scoreFromFinalizeResponse, parseGitHubSeedState, uploadRunBlobs, isPreSatisfied } from '../../chunk-CTA54N4K.js';
+import { DEFAULT_CONTROL_PLANE_URL, DEFAULT_DASHBOARD_URL, clearLocalCredentials, friendlyHostedError, SESSION_TWIN_NAMES, runSessionCreate, runSessionList, runSessionStop, resolveCredentials, runTaskHosted, discoverRunSet, VERDICT_ARTIFACT_VERSION, persistCredentialsAfterLogin, DEFAULT_DOCS_SITE_ORIGIN, resolveSeams, resolveCachedAgentId, readLinkCache, postAgentResolver, writeLinkCache, ensurePomeGitignored } from '../../chunk-MRCYOSBM.js';
+import { assetPath, runTask, resolvePackageRoot, DEMO_TASK_NAME, demoTaskPath } from '../../chunk-IYMDPMMZ.js';
+import { parseTaskFile, scoreStatus, runScoreLine, readLatestRun, readMetaSummary, outcomeOf, readConfigTwins, scoreCountsSummary, markerFor, criterionMarkerLabel, twinSkipSuffix, readCodeCriteria, createHostedClient, toTwinHttpEvent, redactJsonl, scoreFromFinalizeResponse, parseGitHubSeedState, uploadRunBlobs, isPreSatisfied } from '../../chunk-XAQGX7K2.js';
+import '../../chunk-B7PA7UDX.js';
 import '../../chunk-NW7HGA2K.js';
 import { GMAIL_CHECKS } from '../../chunk-JM6VS62R.js';
 import '../../chunk-3T5XN64P.js';
 import { LINEAR_CHECKS } from '../../chunk-XBT6ZLBG.js';
-import '../../chunk-G6GOCYIT.js';
-import '../../chunk-IK2F7ZA3.js';
-import { TWIN_NAME_LIST, isTwinName, createGitHubSmokeApp } from '../../chunk-JE4H5ODK.js';
-import { readManifest, writeManifest, MANIFEST_JSON, readRequiredManifest, normalizeManifestTwins } from '../../chunk-CXGMLUZ4.js';
+import '../../chunk-Q5NBPR57.js';
+import '../../chunk-S6JLWI4S.js';
+import { TWIN_NAME_LIST, isTwinName, createGitHubSmokeApp } from '../../chunk-SRG22BIH.js';
+import { readManifest, writeManifest, MANIFEST_JSON, readRequiredManifest, normalizeManifestTwins } from '../../chunk-VO2XUPZC.js';
 import '../../chunk-XDU6TD4O.js';
-import { MOUNTED_TWINS, deriveAgentSlug, exitCodeFor, HostedUsageError, HostedOrchError, HostedAuthError, HostedQuotaError } from '../../chunk-BZO3YCJS.js';
+import { MOUNTED_TWINS, deriveAgentSlug, exitCodeFor, HostedUsageError, HostedOrchError, HostedAuthError, HostedQuotaError } from '../../chunk-E7WJ3SRP.js';
 import '../../chunk-CBFKZZBR.js';
 import { TAPE_ASSERTABLE_TOOLS } from '../../chunk-C4BVTUA3.js';
 import { seedSchema } from '../../chunk-HJX25USP.js';
@@ -4652,7 +4653,7 @@ var DEFAULT_AGENT_COMMAND = `node ${DEFAULT_AGENT_FILE}`;
 var MANIFEST_SCHEMA_URL = "https://pome.sh/schemas/v1/pome.json";
 var MAX_UNREADABLE_PATHS_SHOWN = 5;
 function readPackageVersion() {
-  if ("0.27.0".length > 0) return "0.27.0";
+  if ("0.29.0".length > 0) return "0.29.0";
   try {
     const here = dirname(fileURLToPath(import.meta.url));
     const candidates = [
@@ -4896,7 +4897,7 @@ function createProgram() {
   const session = program.command("session").alias("sandbox").description(
     "Hosted sandbox sessions (same API as the dashboard Twins page \u2014 requires login)"
   );
-  session.command("create").description("Create a hosted sandbox session for one or more twins and print its connection info").requiredOption(
+  session.command("create").description("Create a hosted sandbox session for one or more twins and print its connection info").option(
     "--twin <name>",
     // The enumeration is derived, never typed: this line is the public
     // discovery surface for which twins exist, and a hand-written copy of the
@@ -4904,8 +4905,17 @@ function createProgram() {
     // stays editorial — github+gmail is the pairing bundled task 27 exercises —
     // and `session-twin-help.test.ts` runs the twins it names through the same
     // validator, so it cannot rot either.
-    `${SESSION_TWIN_NAMES.join(" | ")}. Repeat the flag for a multi-twin session (e.g. --twin github --twin gmail).`,
+    //
+    // No longer `requiredOption`: a `--seed` file whose envelope names exactly
+    // one twin already says which twin the sandbox is for. Commander would
+    // reject the invocation before the action runs, so the check moved into
+    // `runSessionCreate`, which fails with the same "No twin specified"
+    // sentence when neither source supplies one.
+    `${SESSION_TWIN_NAMES.join(" | ")}. Repeat the flag for a multi-twin session (e.g. --twin github --twin gmail). Optional when --seed names exactly one twin.`,
     (value, previous = []) => [...previous, value]
+  ).option(
+    "--seed <path>",
+    "Start the sandbox from a JSON or YAML seed file instead of each twin's default. A seed REPLACES the default; it does not merge. Same file `pome twin start --seed` takes; write one with `pome twin seed <name>`."
   ).option(
     "--api-url <url>",
     "Control-plane URL",
@@ -4928,10 +4938,11 @@ function createProgram() {
         }
         await runSessionCreate({
           apiBaseUrl: opts.apiUrl,
-          twins: opts.twin,
+          twins: opts.twin ?? [],
           showSecrets: opts.showSecrets,
           format,
-          secretsFile: opts.secretsFile
+          secretsFile: opts.secretsFile,
+          seedPath: opts.seed
         });
       } catch (err) {
         console.error(friendlyHostedError(err));
@@ -5103,7 +5114,7 @@ function createProgram() {
         return;
       }
       {
-        const { runDoctorChecks } = await import('../../checks-QM7QOJ6U.js');
+        const { runDoctorChecks } = await import('../../checks-JR4OEKZM.js');
         const { renderDoctorReport } = await import('../../render-ZQQ4UMNO.js');
         const doctorReport = await runDoctorChecks({ mode: useLocal ? "full" : "hosted" });
         if (!doctorReport.ok) {
@@ -5141,7 +5152,7 @@ function createProgram() {
               taskForRuns.config.runs
             );
             if (k > 1) {
-              const { runTrialGroup } = await import('../../runTrialGroup-V3HB57YI.js');
+              const { runTrialGroup } = await import('../../runTrialGroup-XEBG225L.js');
               const fileForRerun = relative(process.cwd(), file);
               const rerunCommand = defaultTask ? options.trials !== void 0 ? `pome run -n ${k}` : "pome run" : `pome run ${fileForRerun && !fileForRerun.startsWith("..") ? fileForRerun : file} -n ${k}`;
               const groupResult = await runTrialGroup({
@@ -5235,7 +5246,7 @@ function createProgram() {
         process.exitCode = 5;
         return;
       }
-      const { runDemo } = await import('../../runDemo-O67ASC54.js');
+      const { runDemo } = await import('../../runDemo-GBPVF5AA.js');
       const result = await runDemo({
         apiBase: opts.apiUrl.replace(/\/$/, ""),
         dashboardBase: process.env.POME_DASHBOARD_URL ?? DEFAULT_DASHBOARD_URL,
@@ -5253,7 +5264,7 @@ function createProgram() {
   program.command("doctor").description(
     "Check the agent\u2194twin wiring: pome.json (or pome.yaml) present + valid, the local twin boots + serves, requests routed to the twin (not a hardcoded production host), egress floor active. On failure prints one named cause (file:line where knowable) + one concrete fix and exits non-zero."
   ).action(async () => {
-    const { runDoctorChecks } = await import('../../checks-QM7QOJ6U.js');
+    const { runDoctorChecks } = await import('../../checks-JR4OEKZM.js');
     const { renderDoctorReport } = await import('../../render-ZQQ4UMNO.js');
     const report = await runDoctorChecks();
     for (const line of renderDoctorReport(report, { passNote: true })) console.error(line);
@@ -5423,18 +5434,27 @@ function createProgram() {
     );
   });
   const twin = program.command("twin").description("Manage local twins");
-  twin.command("start").argument("<name>", `Twin name (${TWIN_NAME_LIST.join(" | ")})`).option(
+  twin.command("start").argument(
+    "[name]",
+    `Twin name (${TWIN_NAME_LIST.join(" | ")}). Optional when --seed names exactly one twin.`
+  ).option(
     "--port <port>",
     "Port to bind (default: $PORT, else GMAIL_TWIN_PORT/3336 for gmail, else 3333)"
   ).option(
     "--seed <path>",
-    "Boot this twin's world from a JSON or YAML file instead of its default. Overrides POME_SEED_JSON."
+    "Boot this twin from a JSON or YAML seed file instead of its default. A seed REPLACES the default; it does not merge. Takes the per-twin envelope { <twin>: { \u2026 } } or one twin's flat seed. Overrides POME_SEED_JSON."
   ).description(
     "Start a standalone twin as a long-lived foreground server (Ctrl-C to stop)"
   ).action(async (name, options) => {
-    const { runTwinStartCommand } = await import('../../twinStart-PDL53BY5.js');
+    const { runTwinStartCommand } = await import('../../twinStart-ZDWFU6M4.js');
     await runTwinStartCommand(name, options);
   });
+  twin.command("seed").argument("<name...>", `Twin name (${TWIN_NAME_LIST.join(" | ")}). Repeat for one file covering several.`).option("--out <path>", "Write to this file instead of stdout. Refuses to overwrite.").description(
+    "Print a starter seed file for a twin, generated from the twin's own starting state"
+  ).action(async (names, options) => {
+    const { runTwinSeedCommand } = await import('../../twinSeed-MOQXJDEG.js');
+    await runTwinSeedCommand(names, options);
+  });
   twin.command("reset").argument("[name]", "Twin name (default: github)", "github").description("Reset standalone twin state").action(async (name) => {
     if (!isTwinName(name)) {
       throw new Error(`Unknown twin '${name}'. Supported: ${TWIN_NAME_LIST.join(", ")}.`);

package/dist/{src-JRBHNT4Y.js → src-5YCI6VIR.js}

@@ -1,6 +1,6 @@
 export { LINEAR_CHECKS } from './chunk-XBT6ZLBG.js';
-import { MCP_PAGE_MAX, defaultSeedState, linearSeedSchema, notFound, badUserInput, MCP_PAGE_DEFAULT, DEFAULT_LINEAR_EMAIL, RELAY_PAGE_MAX, RELAY_PAGE_DEFAULT, STATE_EXPORT_CAP, parseSeed, DEFAULT_LINEAR_CLOCK, LINEAR_PROVIDER_TOKEN_PREFIX, DEFAULT_LINEAR_SID, DEFAULT_SCOPES, linearErrorEnvelope, unauthorizedEnvelope, unsupportedEnvelope, forbiddenEnvelope, assertWebhookUrl, ACCESS_TOKEN_TTL_SECONDS, OAUTH_CODE_TTL_SECONDS, TITLE_MAX_BYTES, BODY_MAX_BYTES, LinearTwinError, GRAPHQL_QUERY_MAX_BYTES, GRAPHQL_SELECTION_DEPTH_MAX } from './chunk-G6GOCYIT.js';
-export { DEFAULT_LINEAR_CLOCK, DEFAULT_LINEAR_EMAIL, DEFAULT_LINEAR_PORT, DEFAULT_LINEAR_SID, DEFAULT_LINEAR_TOKEN, LINEAR_PROVIDER_TOKEN_PREFIX, LinearTwinError, STATE_EXPORT_CAP, assertWebhookUrl, defaultSeedState, linearErrorEnvelope, linearSeedSchema, loadSeedFromEnv, parseSeed, unauthorizedEnvelope, unsupportedEnvelope, webhookUrlError } from './chunk-G6GOCYIT.js';
+import { MCP_PAGE_MAX, defaultSeedState, linearSeedSchema, notFound, badUserInput, MCP_PAGE_DEFAULT, DEFAULT_LINEAR_EMAIL, RELAY_PAGE_MAX, RELAY_PAGE_DEFAULT, STATE_EXPORT_CAP, parseSeed, DEFAULT_LINEAR_CLOCK, LINEAR_PROVIDER_TOKEN_PREFIX, DEFAULT_LINEAR_SID, DEFAULT_SCOPES, linearErrorEnvelope, unauthorizedEnvelope, unsupportedEnvelope, forbiddenEnvelope, assertWebhookUrl, ACCESS_TOKEN_TTL_SECONDS, OAUTH_CODE_TTL_SECONDS, TITLE_MAX_BYTES, BODY_MAX_BYTES, LinearTwinError, GRAPHQL_QUERY_MAX_BYTES, GRAPHQL_SELECTION_DEPTH_MAX } from './chunk-Q5NBPR57.js';
+export { DEFAULT_LINEAR_CLOCK, DEFAULT_LINEAR_EMAIL, DEFAULT_LINEAR_PORT, DEFAULT_LINEAR_SID, DEFAULT_LINEAR_TOKEN, LINEAR_PROVIDER_TOKEN_PREFIX, LinearTwinError, STATE_EXPORT_CAP, assertWebhookUrl, defaultSeedState, linearErrorEnvelope, linearSeedSchema, loadSeedFromEnv, parseSeed, unauthorizedEnvelope, unsupportedEnvelope, webhookUrlError } from './chunk-Q5NBPR57.js';
 import './chunk-JWJYNAWI.js';
 import { routeInputDeclarer, mountDeclaredRoute, UndeclaredInputError } from './chunk-IZFM7W2V.js';
 import { loadMcpToolFixture, deriveMcpToolTable, openTwinDatabase, defineTwin, createApp } from './chunk-E665XWYU.js';

package/dist/twinHarness-CUVRO5IV.js

@@ -0,0 +1,6 @@
+export { UnsupportedTwinError, bootTwin } from './chunk-S6JLWI4S.js';
+export { STRIPE_LOCAL_ACCOUNT_ID } from './chunk-SRG22BIH.js';
+import './chunk-E665XWYU.js';
+import './chunk-6KJC4BTO.js';
+import './chunk-SG6ZTIMT.js';
+import './chunk-CF6EIU2U.js';

package/dist/twinSeed-MOQXJDEG.js

@@ -0,0 +1,48 @@
+import { TWIN_NAMES, isTwinName, TWIN_REGISTRY } from './chunk-SRG22BIH.js';
+import { writeFile } from 'node:fs/promises';
+
+async function generateSeedFile(twins) {
+  if (twins.length === 0) {
+    throw new Error(`No twin specified. Pass at least one of: ${TWIN_NAMES.join(", ")}.`);
+  }
+  for (const twin of twins) {
+    if (!isTwinName(twin)) {
+      throw new Error(`Unknown twin '${twin}'. Supported: ${TWIN_NAMES.join(", ")}.`);
+    }
+  }
+  const duplicates = twins.filter((twin, i) => twins.indexOf(twin) !== i);
+  if (duplicates.length > 0) {
+    throw new Error(`A seed file has one entry per twin, and this one is named twice: ${[...new Set(duplicates)].join(", ")}.`);
+  }
+  const envelope = {};
+  for (const twin of twins) {
+    const entry = TWIN_REGISTRY[twin];
+    envelope[twin] = await entry.parseSeed(await entry.defaultSeed());
+  }
+  return `${JSON.stringify(envelope, null, 2)}
+`;
+}
+async function writeSeedFile(path, text) {
+  try {
+    await writeFile(path, text, { flag: "wx" });
+  } catch (err) {
+    if (err.code === "EEXIST") {
+      throw new Error(
+        `${path} already exists \u2014 delete it or pass a different --out. A seed file is authored content once it is on disk.`
+      );
+    }
+    throw err;
+  }
+}
+async function runTwinSeedCommand(names, options = {}) {
+  const text = await generateSeedFile(names);
+  if (options.out === void 0) {
+    process.stdout.write(text);
+    return;
+  }
+  await writeSeedFile(options.out, text);
+  console.error(`Wrote ${options.out} \u2014 the ${names.join(" + ")} starting seed.`);
+  console.error(`Boot it: pome twin start ${names[0]} --seed ${options.out}`);
+}
+
+export { generateSeedFile, runTwinSeedCommand, writeSeedFile };

package/dist/{twinStart-PDL53BY5.js → twinStart-ZDWFU6M4.js}

@@ -1,5 +1,6 @@
-import { bootTwin } from './chunk-IK2F7ZA3.js';
-import { TWIN_REGISTRY, isTwinName, TWIN_NAMES, defaultPortFor } from './chunk-JE4H5ODK.js';
+import { readSeedFileText, seedForTwin, parseSeedFileText, soleTwinOf, twinsNamedBy } from './chunk-B7PA7UDX.js';
+import { bootTwin } from './chunk-S6JLWI4S.js';
+import { TWIN_REGISTRY, isTwinName, TWIN_NAMES, defaultPortFor } from './chunk-SRG22BIH.js';
 import './chunk-E665XWYU.js';
 import './chunk-6KJC4BTO.js';
 import './chunk-SG6ZTIMT.js';
@@ -10,7 +11,6 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { serve } from '@hono/node-server';
 import { sign } from 'hono/jwt';
-import { parse } from 'yaml';
 
 var STANDALONE_SID = "standalone";
 function resolveStandaloneAuthSecret(twin, env = process.env) {
@@ -35,59 +35,59 @@ function resolveStandaloneAuthSecret(twin, env = process.env) {
   }
   return { secret: randomBytes(32).toString("hex"), source: "ephemeral" };
 }
-async function resolveStandaloneSeed(twin, seedPath, env = process.env) {
-  const entry = TWIN_REGISTRY[twin];
+async function resolveStandaloneSeed(twin, seedPath, env = process.env, seedText) {
   if (seedPath !== void 0) {
-    let raw;
-    try {
-      raw = readFileSync(seedPath, "utf8");
-    } catch (err) {
-      throw new Error(
-        `pome twin start --seed: cannot read ${seedPath}: ${err.message}`
-      );
-    }
+    const raw = seedText ?? readSeedFileText(seedPath, "pome twin start --seed");
+    const origin = `--seed ${seedPath}`;
     return {
-      seedState: await parseWorld(entry, raw, `--seed ${seedPath}`),
+      seedState: await seedForTwin(parseSeedFileText(raw, origin), twin, origin),
       source: "file",
       path: seedPath
     };
   }
   const fromEnv = env.POME_SEED_JSON;
   if (fromEnv !== void 0 && fromEnv !== "") {
-    return { seedState: await parseWorld(entry, fromEnv, "POME_SEED_JSON"), source: "env" };
-  }
-  return { seedState: await entry.defaultSeed(), source: "default" };
-}
-function stripSidecarMeta(seed) {
-  if (seed && typeof seed === "object" && !Array.isArray(seed)) {
-    const { _meta, ...rest } = seed;
-    return rest;
+    return {
+      seedState: await seedForTwin(
+        parseSeedFileText(fromEnv, "POME_SEED_JSON"),
+        twin,
+        "POME_SEED_JSON"
+      ),
+      source: "env"
+    };
   }
-  return seed;
+  return { seedState: await TWIN_REGISTRY[twin].defaultSeed(), source: "default" };
 }
-async function parseWorld(entry, raw, origin) {
-  let parsed;
-  try {
-    parsed = parse(raw);
-  } catch (err) {
-    throw new Error(`${origin} is not valid JSON or YAML: ${err.message}`);
+function resolveStandaloneTwin(name, seedPath, seedText) {
+  if (name !== void 0) {
+    if (!isTwinName(name)) {
+      throw new Error(`Unknown twin '${name}'. Supported: ${TWIN_NAMES.join(", ")}.`);
+    }
+    return name;
   }
-  try {
-    return await entry.parseSeed(stripSidecarMeta(parsed));
-  } catch (err) {
-    throw new Error(`${origin} is not a world this twin can boot: ${err.message}`);
+  if (seedPath === void 0 || seedText === void 0) {
+    throw new Error(
+      `pome twin start: name a twin (${TWIN_NAMES.join(", ")}), or pass a --seed file whose envelope names exactly one.`
+    );
   }
+  const origin = `--seed ${seedPath}`;
+  const file = parseSeedFileText(seedText, origin);
+  const sole = soleTwinOf(file);
+  if (sole !== void 0) return sole;
+  const named = twinsNamedBy(file);
+  throw new Error(
+    named.length === 0 ? `${origin} is a flat seed, so it does not name a twin. Pass the name: pome twin start <${TWIN_NAMES.join("|")}> --seed ${seedPath}` : `${origin} names ${named.length} twins (${named.join(", ")}), so it does not say which one to start. Pass the name: pome twin start ${named[0]} --seed ${seedPath}`
+  );
 }
-async function runTwinStartCommand(name, options) {
-  if (!isTwinName(name)) {
-    throw new Error(`Unknown twin '${name}'. Supported: ${TWIN_NAMES.join(", ")}.`);
-  }
+async function runTwinStartCommand(nameArg, options) {
+  const seedText = options.seed === void 0 ? void 0 : readSeedFileText(options.seed, "pome twin start --seed");
+  const name = resolveStandaloneTwin(nameArg, options.seed, seedText);
   const portRaw = options.port ?? defaultPortFor(name, process.env);
   const port = Number(portRaw);
   if (!Number.isInteger(port) || port < 1 || port > 65535) {
     throw new Error(`pome twin start: invalid --port "${portRaw}"`);
   }
-  const world = await resolveStandaloneSeed(name, options.seed);
+  const world = await resolveStandaloneSeed(name, options.seed, process.env, seedText);
   const resolved = resolveStandaloneAuthSecret(name);
   process.env.TWIN_AUTH_SECRET = resolved.secret;
   const baseUrl = `http://127.0.0.1:${port}`;
@@ -130,11 +130,15 @@ async function runTwinStartCommand(name, options) {
   }
   console.log(`Pome ${name} twin listening at ${restUrl}`);
   if (world.source === "file") {
-    console.log(`World: seeded from ${world.path}.`);
+    console.log(`Seed: ${world.path} (replaces the ${name} twin's default).`);
   } else if (world.source === "env") {
-    console.log("World: seeded from POME_SEED_JSON (--seed <path> overrides it).");
+    console.log(
+      `Seed: POME_SEED_JSON (replaces the ${name} twin's default; --seed <path> overrides it).`
+    );
   } else {
-    console.log(`World: the ${name} twin's default (pass --seed <path> for your own).`);
+    console.log(
+      `Seed: the ${name} twin's default (pass --seed <path>, or write one with \`pome twin seed ${name}\`).`
+    );
   }
   if (resolved.source === "persisted") {
     console.log(
@@ -161,4 +165,4 @@ async function runTwinStartCommand(name, options) {
   process.once("SIGTERM", shutdown);
 }
 
-export { resolveStandaloneAuthSecret, resolveStandaloneSeed, runTwinStartCommand };
+export { resolveStandaloneAuthSecret, resolveStandaloneSeed, resolveStandaloneTwin, runTwinStartCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pome-sh/cli",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Digital-twin testing for AI agents \u2014 run tasks against resettable local or hosted twins and record tool-call traces for evaluation on pome.sh.",
   "keywords": [
     "ai",

package/dist/twinHarness-YOVJR72F.js

@@ -1,6 +0,0 @@
-export { UnsupportedTwinError, bootTwin } from './chunk-IK2F7ZA3.js';
-export { STRIPE_LOCAL_ACCOUNT_ID } from './chunk-JE4H5ODK.js';
-import './chunk-E665XWYU.js';
-import './chunk-6KJC4BTO.js';
-import './chunk-SG6ZTIMT.js';
-import './chunk-CF6EIU2U.js';