@volter/supercode-orchestrator 0.5.207 → 0.5.208

package/loop.mjs

@@ -4,13 +4,14 @@
 // This is the only module that performs I/O for the loop. It holds the single
 // state value, the vault, the SDK client, the adapters, and an injected clock.
 
-import { mkdirSync, writeFileSync, existsSync, readdirSync, readFileSync, renameSync, unlinkSync } from 'node:fs';
+import { mkdirSync, writeFileSync, existsSync, readdirSync, readFileSync, renameSync, unlinkSync, realpathSync } from 'node:fs';
 import { basename, join, dirname } from 'node:path';
 import { step, leaseId } from './reducer.mjs';
 import * as events from './events.mjs';
-import { read, save, retainWorld, releaseWorld } from './orchestration.mjs';
+import { read, save, retainWorld, releaseWorld, refreshVault } from './orchestration.mjs';
 import { INSTRUCTION_ARGUMENTS, NAME_ARGUMENTS, activationEnv, activationCwd, workerCwd, declareWorkerFolder, declareWorkerHome, approvalPolicy, sandboxArguments, limitArguments, materializePersona, materializeSkills, modelArguments, turnCounter, userHomeArguments, userHomePersona } from './activation.mjs';
-import { workerRoute } from './worker-route.mjs';
+import { workerRoute, codexPaneRoute } from './worker-route.mjs';
+import { projectCodexPaneResume } from './codex-pane-resume.mjs';
 import { hermesAccess, hermesApproval, untrustedServerVerdict, hermesToolEnv, memorySnapshot, mirrorSession, mirrorState, recordIncident, sealMirror } from './hermes-cli.mjs';
 import { hermesSessionKey, homeChannel } from './ir.mjs';
 import { surfaceKeyString } from './ir.mjs';
@@ -536,6 +537,50 @@ export class Orchestrator {
     return runtime.handle;
   }
 
+  /** A private local preparation door for an explicit headful mailbox main.
+   * It returns only launch metadata and the configured forward's stand-in key;
+   * it creates no hosted conversation, controller lease, process or first turn. */
+  async prepareMainPane({ directory, name, resume = null }) {
+    if (typeof directory !== 'string' || typeof name !== 'string' || !/^[A-Za-z0-9._-]+$/.test(name))
+      throw new Error('a headful main needs its exact profile directory and agent name');
+    const folder = realpathSync(directory);
+    const profiles = Object.values(this.state.profiles).filter(profile => {
+      try { return realpathSync(profile.dir) === folder; } catch { return false; }
+    });
+    if (!profiles.length) throw Object.assign(new Error('this home has no profile at that directory'), { code: 'not_this_home' });
+    if (profiles.length !== 1) throw new Error('the directory names more than one profile; no main was prepared');
+    const profile = profiles[0], worker = profile.worker;
+    if (worker?.harness !== 'codex') throw new Error('the selected main profile does not run Codex');
+    refreshVault(this.state, this.vault);
+    const route = codexPaneRoute(profile, worker, this.vault);
+    if (resume !== null) {
+      if (resume.harness !== 'codex' || typeof resume.session_id !== 'string' || resume.storage?.kind !== 'file')
+        throw new Error('a main resume needs its exact Codex transcript locator');
+      projectCodexPaneResume(route.env.CODEX_HOME, resume.storage.path, resume.session_id);
+    }
+    const context = process.env.SUPERCODE_CONTEXT, scope = agentScope(context);
+    const agent = await localProfileAgent({ root: this.state.root, org: scope.org, server: scope.server,
+      profiles: this.state.profiles, profile: profile.name, agent: name, declarations: this.state.agents });
+    const env = { ...route.env, ...agentEnvironment(agent, { root: this.state.root,
+      context: localReaderContext(scope.org, agent.identity.id) ?? undefined, main: true }) };
+    // The headful main uses the same profile-owned MCP door and identity
+    // preamble. The returned plan carries no configured server credentials.
+    mountOrchestratorMcp({ root: this.state.root, profile, harness: 'codex',
+      socketPath: this.bridge?.path ?? socketPathFor(this.state.root), vault: this.vault,
+      agentId: agent.identity.id });
+    const instructions = agentPreamble(agent, { main: true,
+      previous: localAgentSessions(this.state.root, scope.org, agent.identity.id) });
+    const arguments_ = [...route.args, ...INSTRUCTION_ARGUMENTS.codex(instructions)];
+    if (resume === null) {
+      arguments_.push(...modelArguments({ ...worker, model: route.model }), '--ask-for-approval', approvalPolicy(profile, 'codex'));
+      arguments_.push(...sandboxArguments(profile, 'codex'));
+      if (worker.reasoning_effort) arguments_.push('-c', `model_reasoning_effort=${JSON.stringify(worker.reasoning_effort)}`);
+    }
+    declareWorkerHome({ harness: 'codex', env, cwd: folder, log: (level, text) => this.log(level, text) });
+    return { ran: `prepared a headful main for profile ${profile.name}`, program: 'codex',
+      profile: profile.name, cwd: folder, arguments: arguments_, env };
+  }
+
   /**
    * A new concurrent session of this profile's agent, asked for on its behalf (operator `sessions.launch`): the agent is
    * the one this home holds for the profile, and must be the one asked for. The session is composed by startRuntime
@@ -570,6 +615,8 @@ export class Orchestrator {
       const native=prior.session_ref.slice(prior.session_ref.indexOf(':')+1);
       const page=await this.client.discover({harnesses:[locator.harness],query:native,limit:200});
       target=page.sessions.find(item=>item.locator.harness===locator.harness&&item.locator.session_id===native)?.locator;
+      // a source still being read is no proof the retained session is gone: no replacement is made either way
+      if(!target&&page.reconciling?.length)throw new Error(`retained fork session cannot be confirmed yet: the session index is still reading ${page.reconciling.join(', ')}; no replacement was created`);
       if(!target)throw new Error('retained fork session is not available; no replacement was created');
     }else {
       const loaded=await this.client.loadWindow(locator,{message_limit:1});
@@ -814,6 +861,7 @@ export class Orchestrator {
     if (locator.storage) return locator;
     const found = await this.client.request('harness.v1.sessions.discover', { query: locator.session_id, harnesses: [locator.harness], limit: 200 });
     const whole = found.sessions?.find((item) => item.locator?.harness === locator.harness && item.locator?.session_id === locator.session_id)?.locator;
+    if (!whole && found.reconciling?.length) throw new Error(`${locator.harness}:${locator.session_id} cannot be found yet: the session index is still reading ${found.reconciling.join(', ')}`);
     if (!whole) throw new Error(`${locator.harness}:${locator.session_id} is not in its harness catalogue`);
     return whole;
   }

package/mcp/bridge.mjs

@@ -123,7 +123,10 @@ async function dispatch(orch, call, log) {
 async function dispatchOperator(orch, { op, args, profile }, log) {
   const name = typeof profile === 'string' && profile ? profile : 'default';
   let answer;
-  if (op === 'agents.fork') {
+  if (op === 'agents.main_plan') {
+    try { answer = { ok: true, result: await orch.prepareMainPane(args ?? {}) }; }
+    catch (error) { answer = { ok: false, error: error.message, ...(error.code ? { code: error.code } : {}) }; }
+  } else if (op === 'agents.fork') {
     // Operation `fork`: a declared child agent, its profile a copy of the parent's, its session a fork of the parent's.
     try {
       const a = args ?? {};

package/mcp/hermes-kanban-tools.json

@@ -46,7 +46,11 @@
         },
         "include_archived": {
           "type": "boolean",
-          "description": "Include archived tasks. Defaults to false."
+          "description": "Include cancelled and archived cards and their tasks. Defaults to false."
+        },
+        "include_subtasks": {
+          "type": "boolean",
+          "description": "Include subtasks as separate rows. Defaults to false; use kanban_show to read a card's tasks inside it."
         },
         "limit": {
           "type": "integer",

package/ontology.d.ts

@@ -1,7 +1,7 @@
 // GENERATED from `supercode ontology schema` — do not edit; run node sdk/orchestrator/scripts/generate-types.mjs
 //
-// The Rust records in `crates/interchange/src/world/` and
-// `crates/interchange/src/ontology/` are the source of truth (`docs/ONTOLOGY.md` §2).
+// The committed `sdk/interchange/ontology-schemas.json` contracts own these types.
+// Native serde records remain only with the capabilities still using them.
 
 /** The access record, as Hermes's stores hold it. */
 export interface Access {
@@ -45,8 +45,6 @@ export interface AgentDecl {
   label?: string | null;
   /** The agent it is declared under, if not the home's root. */
   parent?: string | null;
-  /** A person set on purpose as its sponsor; absent, the sponsor is inherited. */
-  sponsor?: string | null;
   /** What a source format said about it that the IR has no field for, verbatim. */
   residue?: Record<string, unknown>;
 }
@@ -115,7 +113,7 @@ export interface Binding {
 
 /**
  * A per-action gate on a profile's agents: a start or resume over it is refused, with the reason,
- * and the refusal is told to the manager and the sponsor. It never pauses or ends anything itself.
+ * and the refusal is told to the manager. It never pauses or ends anything itself.
  */
 export interface Budget {
   /** The window. */
@@ -390,19 +388,7 @@ export type FireStatus =
   | 'unknown';
 
 /** Observations a role can subscribe to, separate from a card's transition events. */
-export type FleetEventKind =
-  /** A native session process first observed running. */
-  | 'session_started'
-  /** A known native session observed running in a new process incarnation. */
-  | 'session_resumed'
-  /** A native source reports a session process ended; unavailable sources are not ends. */
-  | 'session_ended'
-  /** More than one observed live process incarnation names the same native session. */
-  | 'duplicate_session_process'
-  /** A card's native session reports that it needs its user's input. */
-  | 'card_waiting_on_user'
-  /** A machine's health source reports a critical alarm. */
-  | 'machine_health_crit';
+export type FleetEventKind = 'session_started' | 'session_resumed' | 'session_ended' | 'duplicate_session_process' | 'card_waiting_on_user' | 'machine_health_crit';
 
 /** A conversation moved (or moving) to another surface — Hermes `handoff_*`. */
 export interface Handoff {
@@ -836,7 +822,7 @@ export type SecretRef =
   /** A key in the home's own `.env` file. */
   | { dotenv: string };
 
-/** A session's usage, kept on the session and summed upward (session → agent → sponsor → Org). */
+/** A session's usage, kept on the session and summed upward (session → agent → Org). */
 export interface SessionUsage {
   /** The agent the session belongs to, when it has one. */
   agent?: string | null;
@@ -1134,11 +1120,6 @@ export interface Workflow {
   params?: Record<string, unknown>;
   /** Who acts on a card, each an expression naming a profile (`implementer: card.assignee`) or a person. */
   roles?: Record<string, Expr>;
-  /**
-   * Opt-in fleet observations delivered as mail to each role's declared addresses. These are not card
-   * transitions and grant no observation or machine authority. The manager is an implicit workflow role.
-   */
-  listeners?: Record<string, RoleFleetListener>;
   /** Where a new card starts: the first transition whose guard holds. */
   initial: Transition[];
   /** Every status, by name. */
@@ -1152,4 +1133,6 @@ export interface Workflow {
    * are), the event kinds it hears and the template each is told in. A kind not named is not sent.
    */
   notify?: Record<string, Record<string, string>>;
+  /** Role fleet listeners; a declaration grants no machine or mailbox authority. */
+  listeners?: Record<string, RoleFleetListener>;
 }

package/orchestration.mjs

@@ -150,7 +150,7 @@ export async function load(root) {
   const { orchestration, vault_keys } = await through((d) => d.orchestrationLoad({ root }));
   let vault = readVault(orchestration);
   if (vault_keys.some((k) => !vault.has(k))) {
-    await through((d) => d.orchestrationSave({ root, orchestration }));
+    await through((d) => d.orchestrationSave({ root, orchestration, preserve_workflow: true }));
     vault = readVault(orchestration);
     const missing = vault_keys.filter((k) => !vault.has(k));
     if (missing.length) throw new Error(`${root}: ${missing.join(', ')} referenced but not in .env after normalization`);
@@ -164,12 +164,15 @@ export async function read(root) {
 }
 
 /**
- * `save(state, root)` — our folder, canonical and byte-stable: an artifact whose record has not changed keeps its bytes.
+ * `save(state, root)` — persist runtime state, preserving the home's workflow.yaml.
+ * Board policy belongs to the live home, not the runtime's earlier snapshot. Full
+ * home creation/replacement uses orchestrationSave or importFrom explicitly.
+ * Other artifacts are canonical and byte-stable when their record has not changed.
  * Answers the entries the door could not read (`rejected`, each `{ collection, key, reason, kept_stored }`): each was
  * written as the home last held it, or left out when it held none, and none refuses the rest of the save.
  */
 export async function save(state, root = state.root) {
-  const saved = await through((d) => d.orchestrationSave({ root, orchestration: persistedView(state) }));
+  const saved = await through((d) => d.orchestrationSave({ root, orchestration: persistedView(state), preserve_workflow: true }));
   return { rejected: Array.isArray(saved?.rejected) ? saved.rejected : [] };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.5.207",
+  "version": "0.5.208",
   "type": "module",
   "description": "The orchestrator runtime over the Volter Harness ontology: one typed operational model whose folder is its serialization, read and written through the harness orchestration doors (docs/ORCHESTRATOR-IR.md)",
   "exports": {
@@ -32,10 +32,10 @@
     "check-types": "node scripts/generate-types.mjs --check"
   },
   "dependencies": {
-    "@volter/supercode-teams": "^0.3.344",
+    "@volter/supercode-teams": "^0.3.345",
     "@volter/supercode-terminal": "^0.3.10",
     "@volter/supercode-harness-sdk": "^0.3.104",
-    "@volter/teams": "0.2.96",
+    "@volter/teams": "0.2.98",
     "@volter/ztrack": "^2.4.23",
     "yaml": "^2.9.0"
   },
@@ -61,5 +61,6 @@
     "board",
     "apply",
     "README.md"
-  ]
+  ],
+  "gitHead": "db4a88b4d2f670654fa8e57dbc3e93c7daa8d2bb"
 }

package/worker-route.mjs

@@ -27,9 +27,9 @@
 //
 // A route this table does not have is refused by name at launch, never run on the worker's default:
 // that would spend on a model nobody chose.
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { MODEL_ARGUMENTS } from './activation.mjs';
+import { MODEL_ARGUMENTS, materializePersona, materializeSkills } from './activation.mjs';
 
 /** The Codex provider id a Hermes provider is served under. */
 const PROVIDER_ID = { custom: 'hermes_custom', openai: 'openai', 'openai-codex': 'hermes_codex' };
@@ -75,6 +75,7 @@ export function workerRoute(profile, worker, vault) {
     const forward = vault?.get?.('HERMES_CODEX_BASE_URL') ?? process.env.HERMES_CODEX_BASE_URL;
     if (!forward) throw new Error('model.provider openai-codex needs the Codex forward (HERMES_CODEX_BASE_URL in the home\'s .env, which the kit\'s start writes); refused rather than run on a login the worker would have to hold');
     table.base_url = forward;
+    table.requires_openai_auth = false;
     table.env_key = LITERAL_KEY_ENV;
     env[LITERAL_KEY_ENV] = 'valve';
     writeProviderTable(join(profile.dir, 'codex'), id, table);
@@ -126,7 +127,7 @@ function writeProviderTable(home, id, table) {
   const file = join(home, 'config.toml');
   const text = existsSync(file) ? readFileSync(file, 'utf8') : '';
   const header = `[model_providers.${id}]`;
-  const block = [header, ...Object.entries(table).map(([k, v]) => `${k} = ${JSON.stringify(String(v))}`)].join('\n');
+  const block = [header, ...Object.entries(table).map(([k, v]) => `${k} = ${typeof v === 'boolean' ? String(v) : JSON.stringify(String(v))}`)].join('\n');
   const lines = text.split('\n');
   const start = lines.findIndex((line) => line.trim() === header);
   let next;
@@ -138,3 +139,30 @@ function writeProviderTable(home, id, table) {
   }
   if (next !== text) writeFileSync(file, next, { mode: 0o600 });
 }
+
+/** The headful Codex lane must never fall back to the shared ChatGPT login.
+ * This returns only the configured forward's stand-in key and provider flags;
+ * it neither copies a credential nor starts a program or login. */
+export function codexPaneRoute(profile, worker, vault) {
+  if (worker?.harness !== 'codex' || hermesModel(profile)?.provider !== 'openai-codex')
+    throw new Error('headful Codex requires model.provider openai-codex and its configured HERMES_CODEX_BASE_URL; no shared-login pane was launched');
+  if (worker.home === 'user') throw new Error('headful Codex requires a profile home; no shared-login pane was launched');
+  const forward = vault?.get?.('HERMES_CODEX_BASE_URL') ?? process.env.HERMES_CODEX_BASE_URL;
+  if (!forward) throw new Error('headful Codex requires the configured HERMES_CODEX_BASE_URL; no shared-login pane was launched');
+  let endpoint;
+  try { endpoint = new URL(forward); } catch { throw new Error('the configured Codex forward is not an HTTP endpoint; no pane was launched'); }
+  if (!['http:', 'https:'].includes(endpoint.protocol) || endpoint.username || endpoint.password)
+    throw new Error('the configured Codex forward must be HTTP(S) without URL credentials; no pane was launched');
+  const home = join(profile.dir, 'codex');
+  if (Object.hasOwn(worker.env ?? {}, 'CODEX_HOME') && worker.env.CODEX_HOME !== home)
+    throw new Error('headful Codex has a different worker.env.CODEX_HOME; no shared-login pane was launched');
+  // lstat includes a dangling auth symlink. Do not read, unlink or migrate it.
+  try {
+    lstatSync(join(home, 'auth.json'));
+    throw new Error('the headful Codex profile home holds an auth.json entry; a login-free home is required and no credential was changed');
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  materializePersona(profile);
+  materializeSkills(profile);
+  const route = workerRoute(profile, worker, vault);
+  return { ...route, env: { CODEX_HOME: home, ...route.env } };
+}