c8ctl-plugin-nano 1.55.1 → 1.56.1

package/README.md

@@ -980,6 +980,59 @@ How it works and where things live:
 - Stopping is SIGTERM → grace → SIGKILL, per worker and for the daemon; `stop`
   always clears `supervisor.json` so a stale marker never wedges a future start.
 
+### Surviving SSH logout: `supervisor install` / `uninstall`
+
+On **macOS**, a supervisor started over SSH is bound to your SSH login session's
+launchd/bootstrap context. When you **log out of that SSH session**, macOS tears
+the per-session context down and the orphaned daemon + workers lose their
+network / mDNS resolution path — the fleet does **not** exit cleanly, it
+**wedges**: the activation loop spins on `SDK activateJobs failed: fetch failed`
+forever and claims **zero** jobs (workers may still show `running` / agentic
+`disconnected`). `setsid`/double-fork detachment is not enough there — the daemon
+must live in a **persistent per-user launchd domain** (`gui/$UID`). **Linux is
+unaffected**: under systemd-logind with the default `KillUserProcesses=no` a
+`setsid`'d daemon keeps full network access after logout.
+
+Give the supervisor a session-independent launch path so the fleet survives
+logout and comes back at login/reboot:
+
+```bash
+c8ctl nano supervisor install     # install + start the service
+c8ctl nano supervisor uninstall   # stop + remove it
+```
+
+- **macOS** — writes a per-user **LaunchAgent** and bootstraps it into `gui/$UID`
+  (`launchctl bootstrap gui/$UID …`, `RunAtLoad`, crash-only `KeepAlive`). The
+  plist lives at `~/Library/LaunchAgents/io.nanobpm.c8ctl-nano.supervisor.<hash>.plist`
+  (the `<hash>` is derived from the state home, so distinct `C8CTL_NANO_HOME`
+  instances get distinct services).
+- **Linux** — writes a `systemd --user` unit
+  (`~/.config/systemd/user/c8ctl-nano-supervisor-<hash>.service`), enables + starts
+  it, and turns on **lingering** (`loginctl enable-linger`) so it survives logout
+  even where `KillUserProcesses=yes`. Where `systemd --user` is unavailable, no
+  service is needed — the existing `setsid` daemon already survives logout — and
+  `install` says so.
+- The service inherits only a **curated env** (`PATH`, `HOME`, `LANG`,
+  `C8CTL_NANO_HOME`, the CLI entry) — never your whole SSH environment — so
+  short-lived tokens are not persisted into a plist/unit that outlives the session.
+- `KeepAlive`/`Restart` are **crash-only**: a `supervisor stop` (clean exit) stays
+  down; only a crash is restarted.
+
+When the service **is installed**, every path that starts the daemon
+(`supervisor start`, and a bare `supervisor` / `supervisor attach`) brings it up
+**through the service**: it kickstarts the LaunchAgent when a clean `stop` left it
+down (a plain `kickstart`, never `-k`, so a running fleet is not bounced) and then
+**adopts** that service-owned daemon instead of spawning a second, session-bound
+one. Only if the service cannot be started does it fall back to a detached spawn
+(saying so).
+
+When you run `supervisor start` or `attach` **over SSH on macOS without the
+installed service**, the CLI **auto-reparents** the daemon into the `gui/$UID`
+launchd domain (equivalent to `install`) so it survives logout, and tells you. If
+it cannot (e.g. `launchctl` is unavailable, or you set `C8CTL_NANO_NO_LAUNCHD=1`),
+it prints a prominent **warning** pointing at `supervisor install` instead of
+silently leaving a fleet that will wedge on logout.
+
 ## Composing a workforce: `workforce`
 
 `supervisor` is imperative — you compose a fleet with a `start --worker …` plus a

package/agent-instance.mjs

@@ -0,0 +1,451 @@
+// Engine-native AgentInstance / AgentHistory producer (issue #194).
+//
+// When the harness activates a job whose element carries
+// `zeebe:agentDefinition agentType="external"`, this module mints an engine-native
+// `AgentInstance` (Camunda 8.10 / nanobpmn) and streams the agent's ACP turns into
+// the append-only `AgentHistory` via the host-provided `@camunda8/orchestration-cluster-api`
+// SDK client (`createAgentInstance` / `updateAgentInstance`). This is the DURABLE
+// historical/metrics producer that replaces the fragile app-side transcript relay
+// side-channel — the relay stays as a live overlay; nothing here removes it.
+//
+// The ACP → AgentHistory translation is a port of the canonical
+// `@nanobpm/agentic/session/acp` `classifyUpdate` bridge (the same classifier the
+// transcript-chunk producer uses), so a producer and the engine's read model can
+// never diverge on the semantic shape of a turn.
+//
+// Everything at the process edge is injected (the SDK client, the classifier, the
+// clock), so the producer is driven deterministically under `node --test` with an
+// in-memory fake client. The producer is ENTIRELY best-effort: a failure to mint or
+// append an AgentInstance must NEVER crash the harness or change `job.complete`
+// behaviour — the AgentInstance lifecycle is orthogonal to job completion.
+
+import { sessionAcp as defaultSessionAcp } from './agentic.mjs';
+
+// The two AgentInstance surfaces we call on the host SDK client. A client missing
+// either method (an older SDK) disables the producer rather than throwing.
+const SDK_CREATE = 'createAgentInstance';
+const SDK_UPDATE = 'updateAgentInstance';
+
+const isNonBlank = (v) => v != null && String(v).trim() !== '';
+const isPlainObject = (v) => v != null && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * Is this activated job an `external` (job-backed) agent job — i.e. one whose
+ * element carries `zeebe:agentDefinition agentType="external"`?
+ *
+ * The engine surfaces exactly this eligibility as the pair of fields it stamps on
+ * an external agent job's activation: an opaque per-activation `jobLease` token
+ * (distinct from the job's `deadline`; nanobpmn #1106) plus the `elementInstanceKey`
+ * the AgentInstance correlates on. The engine-native `aiAgentTask`/`aiAgentSubProcess`
+ * variants auto-mint their AgentInstance and never create an activatable job, so any
+ * job a worker actually activates that carries a lease token IS an external agent
+ * job. Absence of either field means "not an external agent job" → the producer
+ * stays fully inert (no behaviour change for ordinary service jobs).
+ */
+export function isExternalAgentJob(job) {
+  if (!isPlainObject(job)) return false;
+  return isNonBlank(job.jobLease) && isNonBlank(job.elementInstanceKey);
+}
+
+/** Best-effort provider inference from a model identifier (openai/anthropic/…). */
+export function inferProvider(model) {
+  const m = String(model || '').toLowerCase();
+  if (!m) return 'unknown';
+  if (/(gpt|o\d|davinci|openai)/.test(m)) return 'openai';
+  if (/(claude|opus|sonnet|haiku|anthropic)/.test(m)) return 'anthropic';
+  if (/(gemini|palm|bison|google)/.test(m)) return 'google';
+  if (/(llama|meta)/.test(m)) return 'meta';
+  if (/(mistral|mixtral)/.test(m)) return 'mistral';
+  if (/(deepseek)/.test(m)) return 'deepseek';
+  if (/(qwen)/.test(m)) return 'qwen';
+  if (/(kimi|moonshot)/.test(m)) return 'moonshot';
+  if (/(grok|xai)/.test(m)) return 'xai';
+  return 'unknown';
+}
+
+/**
+ * Seed the concrete agent `definition` (model, provider, systemPrompt) from the
+ * actual worker/model that claimed the job. The static `agentDefinition` marker is
+ * only the eligibility flag; the concrete definition is runtime — the model comes
+ * from the worker profile, the systemPrompt from the resolved base prompt.
+ */
+export function deriveAgentDefinition({ profile, envelope } = {}) {
+  const model = isNonBlank(profile?.model) ? String(profile.model) : 'unknown';
+  const provider = isNonBlank(profile?.provider)
+    ? String(profile.provider)
+    : inferProvider(model);
+  const systemPrompt = isNonBlank(envelope?.task?.prompt) ? String(envelope.task.prompt) : '';
+  return { model, provider, systemPrompt };
+}
+
+// Map the ACP classifier's message role to the AgentHistory role enum. ACP has no
+// distinct REASONING role, so a `reasoning` chunk folds into ASSISTANT.
+function historyRole(acpRole) {
+  return acpRole === 'user' ? 'USER' : 'ASSISTANT';
+}
+
+// A short, stable hash for deriving a content-addressed historyItemId when the ACP
+// agent omits a messageId (so identical retried content dedups; new content appends).
+function shortHash(text) {
+  let h = 5381;
+  const s = String(text);
+  for (let i = 0; i < s.length; i++) h = ((h << 5) + h + s.charCodeAt(i)) | 0;
+  return (h >>> 0).toString(36);
+}
+
+// Extract per-call metrics from an ACP update when the agent carries them (many
+// ACP agents do not — a documented ACP fidelity gap — so this is usually absent).
+// Reads the common usage locations and maps to the AgentHistory item metric field
+// names. Returns undefined when nothing usable is present.
+function extractMetrics(update) {
+  const src =
+    (isPlainObject(update?.usage) && update.usage) ||
+    (isPlainObject(update?.tokenUsage) && update.tokenUsage) ||
+    (isPlainObject(update?._meta?.usage) && update._meta.usage) ||
+    (isPlainObject(update?.metrics) && update.metrics) ||
+    null;
+  if (!src) return undefined;
+  const num = (v) => (Number.isFinite(Number(v)) ? Number(v) : undefined);
+  const out = {};
+  const inputTokens = num(src.inputTokens ?? src.input_tokens ?? src.promptTokens ?? src.prompt_tokens);
+  const outputTokens = num(src.outputTokens ?? src.output_tokens ?? src.completionTokens ?? src.completion_tokens);
+  const reasoningTokenCount = num(src.reasoningTokenCount ?? src.reasoning_tokens ?? src.reasoningTokens);
+  const cacheCreationTokenCount = num(src.cacheCreationTokenCount ?? src.cache_creation_input_tokens ?? src.cacheCreationInputTokens);
+  const cacheReadTokenCount = num(src.cacheReadTokenCount ?? src.cache_read_input_tokens ?? src.cacheReadInputTokens);
+  const durationMs = num(src.durationMs ?? src.duration_ms ?? src.latencyMs ?? src.latency_ms);
+  if (inputTokens !== undefined) out.inputTokens = inputTokens;
+  if (outputTokens !== undefined) out.outputTokens = outputTokens;
+  if (reasoningTokenCount !== undefined) out.reasoningTokenCount = reasoningTokenCount;
+  if (cacheCreationTokenCount !== undefined) out.cacheCreationTokenCount = cacheCreationTokenCount;
+  if (cacheReadTokenCount !== undefined) out.cacheReadTokenCount = cacheReadTokenCount;
+  if (durationMs !== undefined) out.durationMs = durationMs;
+  return Object.keys(out).length ? out : undefined;
+}
+
+// A tool-result's `result` becomes an OBJECT content block when it is structured
+// JSON, or a TEXT block when it is a plain string. Null/undefined → empty content.
+function contentForResult(result) {
+  if (result == null) return [];
+  if (typeof result === 'string') return [{ contentType: 'TEXT', text: result }];
+  return [{ contentType: 'OBJECT', object: result }];
+}
+
+/**
+ * Create an AgentInstance producer bound to one activated external agent job.
+ *
+ * Returns a small facade the harness drives:
+ *   - `activate()` — mint the AgentInstance (lease-gated on the job) with the
+ *     opening CONFIGURATION turn. Idempotent: correlates on the elementInstanceKey,
+ *     so a reactivation (ask-a-question loop) folds into the SAME instance and never
+ *     creates a second one.
+ *   - `ingest(rawUpdate)` — feed one raw ACP `session/update` (non-blocking; the SDK
+ *     append is enqueued so the ACP hot path never blocks).
+ *   - `complete(ok)` — drain pending appends, then (on a successful job end) update
+ *     the instance status to COMPLETED. `job.complete` is unchanged and orthogonal.
+ *
+ * @param {object} opts
+ * @param {object} opts.camunda   Host SDK client (createAgentInstance/updateAgentInstance).
+ * @param {object} opts.job       The activated job (jobKey/jobLease/elementInstanceKey/elementId).
+ * @param {object} [opts.profile] The worker profile (model/provider seed the definition).
+ * @param {object} [opts.envelope] The normalized task envelope (task.prompt → systemPrompt).
+ * @param {object} [opts.logger]  Output-mode-aware logger (warn/info/debug).
+ * @param {() => number} [opts.now] Injected clock (ms epoch); defaults to Date.now.
+ * @param {object} [opts.sessionAcp] The ACP classifier surface (defaults to the package bridge).
+ */
+export function createAgentInstanceProducer(opts = {}) {
+  const {
+    camunda,
+    job,
+    profile = {},
+    envelope = {},
+    logger = console,
+    now = () => Date.now(),
+    sessionAcp = defaultSessionAcp,
+  } = opts;
+
+  const classify = typeof sessionAcp?.classifyUpdate === 'function' ? sessionAcp.classifyUpdate : null;
+
+  const jobKey = job?.jobKey != null ? String(job.jobKey) : '';
+  const jobLease = job?.jobLease != null ? String(job.jobLease) : '';
+  const elementInstanceKey = job?.elementInstanceKey != null ? String(job.elementInstanceKey) : '';
+  const elementId = job?.elementId != null ? String(job.elementId) : null;
+
+  // The producer is a no-op unless every precondition holds: a usable SDK client,
+  // an external agent job, and the ACP classifier. Any missing piece leaves the
+  // harness path byte-for-byte unchanged.
+  const usable =
+    !!camunda &&
+    typeof camunda[SDK_CREATE] === 'function' &&
+    typeof camunda[SDK_UPDATE] === 'function' &&
+    !!classify &&
+    isExternalAgentJob(job);
+
+  let disabled = !usable;
+  let agentInstanceKey = null;
+  let activated = false;
+  let loopIteration = 0;
+  let queue = Promise.resolve();
+  // Coalesce streamed message chunks (same messageId + role) into one turn, flushed
+  // on a role/message boundary, a tool event, or completion — the engine dedups on
+  // historyItemId (it does NOT merge), so a turn must be appended exactly once, whole.
+  let pendingMessage = null;
+  // callId → toolName, so a TOOL_RESULT turn can reference the originating call name.
+  const toolNames = new Map();
+
+  const iso = () => new Date(now()).toISOString();
+
+  // Serialize an SDK call onto the queue so appends preserve order and `complete`
+  // can drain them. A rejection is swallowed (best-effort) but never breaks the chain.
+  const enqueue = (fn) => {
+    queue = queue.then(fn).catch((err) => {
+      logger?.debug?.(`AgentInstance producer: SDK call failed — ${err?.message || err}`);
+    });
+    return queue;
+  };
+
+  // Append one AgentHistory turn via updateAgentInstance (one turn per call keeps the
+  // dedup boundary crisp). Only ever runs once the instance is minted.
+  const appendTurn = (turn, status) => {
+    if (disabled || !agentInstanceKey) return;
+    enqueue(async () => {
+      const req = {
+        agentInstanceKey,
+        elementInstanceKey,
+        jobKey,
+        jobLease,
+        history: [turn],
+      };
+      if (status) req.status = status;
+      await camunda[SDK_UPDATE](req);
+    });
+  };
+
+  const flushMessage = () => {
+    if (!pendingMessage) return;
+    const text = pendingMessage.texts.join('');
+    const hasText = text.trim() !== '';
+    const hasMetrics = pendingMessage.metrics !== undefined;
+    const msg = pendingMessage;
+    pendingMessage = null;
+    if (!hasText && !hasMetrics) return;
+    const idBasis = isNonBlank(msg.messageId) ? String(msg.messageId) : `h:${shortHash(text)}`;
+    const turn = {
+      historyItemId: `${msg.role.toLowerCase()}:${idBasis}`,
+      loopIteration: msg.loopIteration,
+      role: msg.role,
+      content: hasText ? [{ contentType: 'TEXT', text }] : [],
+      producedAt: msg.producedAt,
+    };
+    if (msg.role === 'ASSISTANT' && hasMetrics) turn.metrics = msg.metrics;
+    appendTurn(turn, msg.role === 'ASSISTANT' ? 'THINKING' : undefined);
+    // A completed ASSISTANT response ends one loop iteration.
+    if (msg.role === 'ASSISTANT') loopIteration += 1;
+  };
+
+  const onToolCall = (c) => {
+    flushMessage();
+    if (isNonBlank(c.name)) toolNames.set(String(c.callId), String(c.name));
+    const turn = {
+      historyItemId: `toolcall:${c.callId}`,
+      loopIteration,
+      role: 'ASSISTANT',
+      content: [],
+      toolCalls: [
+        {
+          toolCallId: String(c.callId),
+          toolName: isNonBlank(c.name) ? String(c.name) : '',
+          elementId,
+          arguments: isPlainObject(c.args) ? c.args : null,
+        },
+      ],
+      producedAt: iso(),
+    };
+    appendTurn(turn, 'TOOL_CALLING');
+  };
+
+  const onToolResult = (c) => {
+    flushMessage();
+    const turn = {
+      historyItemId: `toolresult:${c.callId}`,
+      loopIteration,
+      role: 'TOOL_RESULT',
+      content: contentForResult(c.result),
+      toolCalls: [
+        {
+          toolCallId: String(c.callId),
+          toolName: toolNames.get(String(c.callId)) || '',
+          elementId,
+          arguments: null,
+        },
+      ],
+      producedAt: iso(),
+    };
+    appendTurn(turn);
+  };
+
+  return {
+    /** True once the AgentInstance has been minted (or is being minted). */
+    get active() {
+      return activated && !disabled;
+    },
+    get agentInstanceKey() {
+      return agentInstanceKey;
+    },
+
+    /**
+     * Mint the AgentInstance (lease-gated) with an opening CONFIGURATION turn that
+     * establishes model/provider/systemPrompt/limits. Idempotent per element
+     * instance — safe to call once per activation; a reactivation reconciles onto
+     * the same instance rather than creating a second one. Best-effort: a rejected
+     * create (e.g. a stale lease) disables the producer and returns false.
+     */
+    async activate() {
+      if (disabled || activated) return this.active;
+      activated = true;
+      const def = deriveAgentDefinition({ profile, envelope });
+      const configTurn = {
+        historyItemId: `configuration:${elementInstanceKey}`,
+        loopIteration: 0,
+        role: 'CONFIGURATION',
+        content: [],
+        producedAt: iso(),
+        model: def.model,
+        provider: def.provider,
+      };
+      if (isNonBlank(def.systemPrompt)) {
+        configTurn.systemPrompt = [{ contentType: 'TEXT', text: def.systemPrompt }];
+      }
+      const limits = deriveLimits(envelope);
+      if (limits) configTurn.limits = limits;
+      try {
+        const res = await camunda[SDK_CREATE]({
+          elementInstanceKey,
+          jobKey,
+          jobLease,
+          history: [configTurn],
+        });
+        agentInstanceKey =
+          (res && (res.agentInstanceKey ?? res.key)) != null
+            ? String(res.agentInstanceKey ?? res.key)
+            : null;
+        if (!agentInstanceKey) {
+          // A reactivation reconciles the auto-minted/existing record; if the create
+          // result carries no key, fall back to the elementInstanceKey correlation is
+          // not possible for updates (they need the agentInstanceKey), so disable.
+          disabled = true;
+          logger?.warn?.('AgentInstance producer: create returned no agentInstanceKey; disabling durable transcript for this job.');
+          return false;
+        }
+        loopIteration = 1;
+        logger?.info?.(`AgentInstance ${agentInstanceKey} minted for element instance ${elementInstanceKey} (job ${jobKey}).`);
+        return true;
+      } catch (err) {
+        disabled = true;
+        logger?.warn?.(`AgentInstance producer: createAgentInstance failed — ${err?.message || err}; continuing without a durable transcript (job completion unaffected).`);
+        return false;
+      }
+    },
+
+    /**
+     * Feed one raw ACP `session/update` (the `params.update`). Non-blocking: the
+     * translated turn's SDK append is enqueued. Malformed/ignored updates are
+     * dropped. Never throws.
+     */
+    ingest(rawUpdate) {
+      if (disabled || !agentInstanceKey) return;
+      let classified;
+      try {
+        classified = classify(rawUpdate);
+      } catch {
+        return;
+      }
+      if (!classified || typeof classified !== 'object') return;
+      try {
+        switch (classified.kind) {
+          case 'message': {
+            const role = historyRole(classified.role);
+            if (
+              pendingMessage &&
+              (pendingMessage.messageId !== classified.messageId || pendingMessage.role !== role)
+            ) {
+              flushMessage();
+            }
+            if (!pendingMessage) {
+              pendingMessage = {
+                role,
+                messageId: classified.messageId ?? null,
+                texts: [],
+                metrics: undefined,
+                loopIteration,
+                producedAt: iso(),
+              };
+            }
+            if (isNonBlank(classified.text)) pendingMessage.texts.push(String(classified.text));
+            const m = extractMetrics(rawUpdate);
+            if (m) pendingMessage.metrics = { ...(pendingMessage.metrics || {}), ...m };
+            break;
+          }
+          case 'tool-call':
+            onToolCall(classified);
+            break;
+          case 'tool-result':
+            onToolResult(classified);
+            break;
+          default:
+            break;
+        }
+      } catch (err) {
+        logger?.debug?.(`AgentInstance producer: ingest failed — ${err?.message || err}`);
+      }
+    },
+
+    /** Drain any queued appends without transitioning status. */
+    async drain() {
+      flushMessage();
+      await queue;
+    },
+
+    /**
+     * End the AgentInstance lifecycle. Flushes any pending message turn, drains the
+     * append queue, then — only on a SUCCESSFUL job end (`ok`) — updates the instance
+     * status to COMPLETED (there is no separate completeAgentInstance verb). On a
+     * failed run the instance is left non-terminal so a retry/reactivation continues
+     * the same instance. Best-effort; never throws; `job.complete` is unaffected.
+     */
+    async complete(ok = true) {
+      if (disabled || !agentInstanceKey) {
+        // Still drain any queued appends so a caller awaiting completion settles.
+        try { await this.drain(); } catch { /* best effort */ }
+        return;
+      }
+      flushMessage();
+      if (ok) {
+        enqueue(async () => {
+          await camunda[SDK_UPDATE]({
+            agentInstanceKey,
+            elementInstanceKey,
+            jobKey,
+            jobLease,
+            status: 'COMPLETED',
+          });
+        });
+      }
+      try { await queue; } catch { /* best effort */ }
+    },
+  };
+}
+
+/**
+ * Derive the agent execution `limits` from the task envelope, when present. Maps the
+ * envelope's `task.maxIterations` onto `maxModelCalls`; token/tool ceilings are not
+ * expressed in the envelope today, so they are left as -1 (no limit). Returns
+ * undefined when nothing constrains the run (the create then defaults all to -1).
+ */
+export function deriveLimits(envelope) {
+  const maxIterations = envelope?.task?.maxIterations;
+  const n = Number(maxIterations);
+  if (Number.isFinite(n) && n > 0) {
+    return { maxModelCalls: Math.trunc(n), maxToolCalls: -1, maxTokens: -1 };
+  }
+  return undefined;
+}

package/c8ctl-plugin.js

@@ -72,6 +72,10 @@ import { createLogRing, resolveLogMaxBytes } from './supervisor-log-ring.mjs';
 // raw ACP `session/update` to the exact transcript-chunk bytes the cockpit decodes,
 // replacing the plugin's former hand-rolled `nwfTranscriptEvent` envelope grammar.
 import { sessionAcp as agenticSessionAcp } from './agentic.mjs';
+// Engine-native AgentInstance / AgentHistory durable-transcript producer (issue
+// #194): mints an AgentInstance for an `external` agent job and appends each ACP
+// turn to the engine's append-only AgentHistory via the host SDK client.
+import { createAgentInstanceProducer, isExternalAgentJob } from './agent-instance.mjs';
 
 const requireFromHere = createRequire(import.meta.url);
 const pluginDir = dirname(fileURLToPath(import.meta.url));
@@ -4879,7 +4883,7 @@ const ACP_MAX_LINE_BYTES = 8 * 1024 * 1024; // 8 MiB
 // and every caller work unchanged. Because the raw stream is JSON-RPC (not human
 // output), `stdout` here is the accumulated human-readable transcript text (what
 // we relay), and `stderr` is the child's real stderr (agent diagnostics).
-function spawnCaptureAcp({ command, args = [], cwd, env, stdinData, timeoutMs, idleTimeoutMs, recoveryWindowMs, relayTap = null, stream = false, streamPrefix = '', onStreamOut, onStreamErr, permission = 'yolo', shell = false }) {
+function spawnCaptureAcp({ command, args = [], cwd, env, stdinData, timeoutMs, idleTimeoutMs, recoveryWindowMs, relayTap = null, stream = false, streamPrefix = '', onStreamOut, onStreamErr, permission = 'yolo', shell = false, onAcpUpdate = null }) {
   return new Promise((resolve) => {
     const logger = getLogger();
     const humanChunks = [];
@@ -5222,7 +5226,17 @@ function spawnCaptureAcp({ command, args = [], cwd, env, stdinData, timeoutMs, i
       }
       // A request or notification FROM the agent.
       if (typeof msg.method === 'string') {
-        if (msg.method === 'session/update') { emitTranscript(msg.params?.update); return; }
+        if (msg.method === 'session/update') {
+          emitTranscript(msg.params?.update);
+          // #194: durable engine-native producer seam. In parallel with the
+          // transcript-chunk relay overlay, hand the SAME raw `session/update` to
+          // the AgentInstance producer so each ACP turn is appended to the engine's
+          // append-only AgentHistory. Best-effort and non-blocking (the producer
+          // enqueues its own SDK append), so a producer failure never disturbs the
+          // ACP loop or the transcript relay. Inert when no producer is wired.
+          if (onAcpUpdate) { try { onAcpUpdate(msg.params?.update); } catch { /* producer best-effort */ } }
+          return;
+        }
         if (msg.method === 'session/request_permission') {
           if (msg.id !== undefined) handlePermission(msg.id, msg.params);
           return;
@@ -5540,7 +5554,7 @@ function baseAgentEnv(profile, job) {
  * Both paths resolve to the same result contract.
  */
 function runAgentJob(profile, job, opts = {}) {
-  const { timeoutMs, idleTimeoutMs, recoveryWindowMs, envelope, sandbox = 'none', image, runId, secretEnv = {}, passThroughSecretNames = [], cwd, extraEnv = {}, profileEnv = {}, resultFile, stream = false, streamPrefix = '', onStreamOut, onStreamErr, args: commandArgs, terminal = 'pipe', protocol = 'pipe', permission = 'yolo', relaySession = null, ptyFactory, nudgePayload = null } = opts;
+  const { timeoutMs, idleTimeoutMs, recoveryWindowMs, envelope, sandbox = 'none', image, runId, secretEnv = {}, passThroughSecretNames = [], cwd, extraEnv = {}, profileEnv = {}, resultFile, stream = false, streamPrefix = '', onStreamOut, onStreamErr, args: commandArgs, terminal = 'pipe', protocol = 'pipe', permission = 'yolo', relaySession = null, ptyFactory, nudgePayload = null, onAcpUpdate = null } = opts;
   // #110: `protocol`/`permission` drive the ACP executor branch below. The
   // pipe/PTY paths are unchanged, so `protocol === 'pipe'` behaviour is identical.
   // A `nudgePayload` (#678) carries the bespoke "re-emit your result" prompt for a
@@ -5628,6 +5642,7 @@ function runAgentJob(profile, job, opts = {}) {
         onStreamOut,
         onStreamErr,
         permission,
+        onAcpUpdate,
       });
     }
 
@@ -7501,6 +7516,25 @@ async function workAgent(req, flags) {
         const runId = randomUUID();
         if (isContainer) liveRunIds.add(runId);
 
+        // #194: durable engine-native AgentInstance producer. For an `external`
+        // agent job (one carrying the activation's lease token + elementInstanceKey)
+        // mint an AgentInstance now — lease-gated on THIS activation — seeding the
+        // concrete definition (model/provider/systemPrompt) from the worker/model
+        // and task prompt. Correlated on the elementInstanceKey, so a reactivation
+        // (ask-a-question loop) folds into the SAME instance rather than a second.
+        // Entirely best-effort and orthogonal to job completion: a mint failure (or
+        // the kill-switch NANO_AGENT_INSTANCE=off) leaves the harness path unchanged.
+        // Each ACP `session/update` is fed to `producer.ingest` (wired via runOpts'
+        // `onAcpUpdate`), which appends the translated turn to AgentHistory; on job
+        // end the instance is driven to COMPLETED (success only) — `job.complete`
+        // fires exactly as before regardless.
+        let agentInstanceProducer = null;
+        const agentInstanceOff = String(process.env.NANO_AGENT_INSTANCE || '').trim().toLowerCase() === 'off';
+        if (!agentInstanceOff && isExternalAgentJob(job)) {
+          agentInstanceProducer = createAgentInstanceProducer({ camunda, job, profile, envelope, logger });
+          try { await agentInstanceProducer.activate(); } catch { /* best effort */ }
+        }
+
         // Fail-closed on a half-specified repository envelope (issue #129,
         // hardening 2): a `repository` block that declares intent (any field set)
         // but whose `url` is absent or not a usable clone target almost always
@@ -7661,6 +7695,11 @@ async function workAgent(req, flags) {
             // spying never corrupts a structured/JSON output mode.
             onStreamOut: stream ? (line) => logger.info(line) : undefined,
             onStreamErr: stream ? (line) => logger.warn(line) : undefined,
+            // #194: feed each raw ACP `session/update` to the durable AgentInstance
+            // producer so its turn is appended to the engine's AgentHistory. Inert
+            // when no producer was minted (non-external job / off / mint failed) and
+            // for non-ACP harnesses (no session/updates are emitted). Best-effort.
+            onAcpUpdate: agentInstanceProducer ? (u) => agentInstanceProducer.ingest(u) : undefined,
           };
           result = await runAgentJob(profile, job, runOpts);
 
@@ -7698,6 +7737,14 @@ async function workAgent(req, flags) {
             }
           }
 
+          // #194: end the AgentInstance lifecycle. Flush any pending turn and drain
+          // the append queue, then drive the instance to COMPLETED on a successful
+          // job end (a failed run leaves it non-terminal so a retry/reactivation
+          // continues the same instance). Best-effort — never disturbs job settlement.
+          if (agentInstanceProducer) {
+            try { await agentInstanceProducer.complete(result.ok); } catch { /* best effort */ }
+          }
+
           // Finalize git only when the harness succeeded — never push a
           // half-finished workspace.
           if (provisioned && result.ok) {
@@ -9277,7 +9324,7 @@ function supervisorRequest(req, { socketPath, timeoutMs, responseTimeoutMs = SUP
  * Ensure a daemon is running, spawning it detached if not, and return its
  * running state. Polls the control socket until it answers a status request.
  */
-async function startSupervisorDaemon() {
+async function startSupervisorDaemon({ adoptOnly = false } = {}) {
   const existing = runningSupervisor();
   if (existing) return existing;
 
@@ -9285,18 +9332,32 @@ async function startSupervisorDaemon() {
   // The state file may be missing (deleted, cleaned up, or not yet written)
   // while a daemon is still listening on the deterministic socket. Adopt that
   // live daemon instead of spawning a second one that would orphan the
-  // original and its workers.
-  try {
-    const res = await supervisorRequest({ op: 'status' }, { socketPath, timeoutMs: 500, responseTimeoutMs: SUPERVISOR_PROBE_RESPONSE_TIMEOUT_MS });
-    if (res && res.ok) {
-      // Re-persist the adopted daemon's state so subsequent pid-based checks
-      // (runningSupervisor()) work immediately, instead of staying broken until
-      // some later command happens to heal supervisor.json.
-      const adopted = runningSupervisor() || stateFromStatus(res, socketPath);
-      try { writeSupervisorState(adopted); } catch { /* best effort */ }
-      return adopted;
-    }
-  } catch { /* no live daemon on the socket — safe to (re)spawn */ }
+  // original and its workers. When a service was just installed/reparented
+  // (adoptOnly), the launchd/systemd-owned daemon may still be booting, so poll
+  // the socket up to the connect timeout rather than racing to spawn a second,
+  // session-bound daemon that would fight it over the same socket/state.
+  const adoptDeadline = adoptOnly ? Date.now() + SUPERVISOR_CONNECT_TIMEOUT_MS : 0;
+  for (;;) {
+    try {
+      const res = await supervisorRequest({ op: 'status' }, { socketPath, timeoutMs: 500, responseTimeoutMs: SUPERVISOR_PROBE_RESPONSE_TIMEOUT_MS });
+      if (res && res.ok) {
+        // Re-persist the adopted daemon's state so subsequent pid-based checks
+        // (runningSupervisor()) work immediately, instead of staying broken until
+        // some later command happens to heal supervisor.json.
+        const adopted = runningSupervisor() || stateFromStatus(res, socketPath);
+        try { writeSupervisorState(adopted); } catch { /* best effort */ }
+        return adopted;
+      }
+    } catch { /* no live daemon on the socket yet */ }
+    if (Date.now() >= adoptDeadline) break;
+    await new Promise((r) => setTimeout(r, 150));
+  }
+
+  if (adoptOnly) {
+    // A service owns the daemon; never spawn a competing session-bound one —
+    // that is exactly the wedge reparenting exists to avoid.
+    throw new Error(`supervisor service was installed but its daemon did not become ready (see ${supervisorDaemonLogFile()})`);
+  }
 
   clearSupervisorState(); // clear any stale marker from a dead daemon
 
@@ -9331,9 +9392,21 @@ async function startSupervisorDaemon() {
   throw new Error(`supervisor daemon did not become ready (see ${logFile})`);
 }
 
+/**
+ * Bring the daemon up under the session-independence policy: re-parent into the
+ * persistent launchd domain when macOS-over-SSH is exposed (or a service is
+ * already installed), then adopt the service-owned daemon instead of spawning a
+ * competing session-bound one. Every command that starts the daemon goes through
+ * here, so no path can silently bypass the policy and recreate the logout wedge.
+ */
+async function startSupervisorWithServicePolicy(logger = getLogger()) {
+  const serviceOwned = await maybeReparentOrWarnOnStart(logger);
+  return startSupervisorDaemon({ adoptOnly: serviceOwned });
+}
+
 async function supervisorStartCmd(req, flags) {
   const logger = getLogger();
-  const state = await startSupervisorDaemon();
+  const state = await startSupervisorWithServicePolicy(logger);
   logger.info(`Supervisor daemon running (pid ${state.pid}).`);
 
   const specs = normalizeArgList(flags?.worker);
@@ -9418,7 +9491,7 @@ async function supervisorAddCmd(req, flags) {
     logger.error('--name cannot be combined with --instances > 1 (each instance needs a distinct name); omit --name to auto-name them.');
     process.exit(1);
   }
-  await startSupervisorDaemon();
+  await startSupervisorWithServicePolicy(logger);
   const workArgs = reconstructWorkArgs(flags);
   let added = 0;
   let failed = 0;
@@ -9680,6 +9753,442 @@ async function attachSupervisorConsole(state) {
   });
 }
 
+// ---------------------------------------------------------------------------
+// Session-independent supervisor service (issue #196).
+//
+// On macOS a supervisor started over SSH is bound to the SSH login session's
+// launchd/bootstrap + audit context. On SSH logout macOS tears that per-session
+// context down and the orphaned daemon + workers lose their network / mDNS
+// resolution path — the fleet does NOT cleanly exit, it WEDGES (the activation
+// loop spins on `activateJobs failed: fetch failed` forever and claims zero
+// jobs). `setsid`/double-fork detachment is not sufficient there: the daemon
+// must live in a persistent per-user launchd domain (`gui/$UID`).
+//
+// Linux is unaffected — under systemd-logind with the default
+// `KillUserProcesses=no` a `setsid`'d daemon keeps full network access after
+// logout — so this is a macOS-specific defect in how the supervisor detaches.
+//
+// The fix gives the supervisor a session-independent launch path symmetric with
+// Linux: `supervisor install` writes a per-user LaunchAgent and bootstraps it
+// into `gui/$UID` (macOS) or a `systemd --user` unit with lingering (Linux),
+// and `supervisor start` over SSH on macOS auto-reparents into that domain (or,
+// when it cannot, WARNS that the fleet will die on logout).
+// ---------------------------------------------------------------------------
+
+/** True when the current process is running inside an SSH login session. */
+function isSshSession(env = process.env) {
+  return Boolean(env.SSH_CONNECTION || env.SSH_CLIENT || env.SSH_TTY);
+}
+
+/** Minimal XML text escaping for the LaunchAgent plist. */
+function xmlEscape(s) {
+  return String(s)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+// Short hash of the (possibly overridden) state home, so distinct
+// C8CTL_NANO_HOME instances get distinct services and never fight over the same
+// launchd label / systemd unit.
+function supervisorServiceHash() {
+  return createHash('sha1').update(getStateHome()).digest('hex').slice(0, 8);
+}
+
+/** Reverse-DNS LaunchAgent label for this state home. */
+function supervisorServiceLabel() {
+  return `io.nanobpm.c8ctl-nano.supervisor.${supervisorServiceHash()}`;
+}
+
+/** Per-user LaunchAgent plist path (macOS). */
+function launchAgentPlistPath() {
+  return join(homedir(), 'Library', 'LaunchAgents', `${supervisorServiceLabel()}.plist`);
+}
+
+/** systemd --user unit file name / path (Linux). */
+function systemdUnitName() {
+  return `c8ctl-nano-supervisor-${supervisorServiceHash()}.service`;
+}
+function systemdUserUnitPath() {
+  const base = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+  return join(base, 'systemd', 'user', systemdUnitName());
+}
+
+/** launchd domain / service targets. */
+function launchdDomainTarget(uid) {
+  return `gui/${uid}`;
+}
+function launchdServiceTarget(uid, label) {
+  return `gui/${uid}/${label}`;
+}
+
+// Curate the env a persistent service should inherit — enough to re-invoke the
+// CLI and locate its state, but NOT the whole SSH environment (which could bleed
+// short-lived tokens into a persistent plist/unit that outlives the session).
+const SUPERVISOR_SERVICE_ENV_KEYS = ['PATH', 'HOME', 'LANG', 'LC_ALL', 'C8CTL_NANO_HOME'];
+function supervisorServiceEnv(env = process.env) {
+  const out = {};
+  for (const k of SUPERVISOR_SERVICE_ENV_KEYS) {
+    if (env[k] != null && env[k] !== '') out[k] = String(env[k]);
+  }
+  // Pin the entry point so the daemon can spawn `work` children even if argv[1]
+  // differs under launchd/systemd.
+  const { entry } = c8ctlInvocation();
+  if (entry) out.C8CTL_NANO_ENTRY = entry;
+  return out;
+}
+
+/**
+ * Build a per-user LaunchAgent plist that runs `nano supervisor __daemon`.
+ * `RunAtLoad` starts it at login/reboot; `KeepAlive`={SuccessfulExit:false}
+ * restarts it only on a crash — an intentional `supervisor stop` exits 0 and
+ * stays down, so the invariant "stop stops the fleet" is preserved.
+ */
+function buildLaunchAgentPlist({ label, exec, entry, env = {}, stdoutPath, stderrPath }) {
+  const args = [exec, entry, 'nano', 'supervisor', '__daemon'];
+  const argXml = args.map((a) => `    <string>${xmlEscape(a)}</string>`).join('\n');
+  const envXml = Object.entries(env)
+    .filter(([, v]) => v != null && v !== '')
+    .map(([k, v]) => `    <key>${xmlEscape(k)}</key>\n    <string>${xmlEscape(String(v))}</string>`)
+    .join('\n');
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${xmlEscape(label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${argXml}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+${envXml}
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ProcessType</key>
+  <string>Background</string>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(stdoutPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(stderrPath)}</string>
+</dict>
+</plist>
+`;
+}
+
+/**
+ * Quote one `ExecStart` argument for a systemd unit. systemd splits the command
+ * line on unquoted whitespace, so any argument containing whitespace or a shell
+ * metacharacter must be double-quoted with C-style escaping inside. A literal
+ * `%` is doubled so systemd never mistakes it for a specifier (e.g. `%h`).
+ */
+function systemdQuoteExecArg(arg) {
+  const s = String(arg).replace(/%/g, '%%');
+  if (s === '') return '""';
+  if (/[\s"'\\`$;&|<>()]/.test(String(arg))) {
+    return `"${s.replace(/[\\"]/g, (c) => `\\${c}`)}"`;
+  }
+  return s;
+}
+
+/**
+ * Render one `Environment=` line for a systemd unit. When the `KEY=VALUE`
+ * assignment contains whitespace or a quote/backslash, the whole assignment is
+ * double-quoted (systemd otherwise splits it into multiple assignments on
+ * whitespace). A literal `%` is doubled so it is not expanded as a specifier.
+ */
+function systemdEnvLine(k, v) {
+  const key = String(k).replace(/%/g, '%%');
+  const val = String(v).replace(/%/g, '%%');
+  const assignment = `${key}=${val}`;
+  if (/[\s"'\\`$]/.test(`${k}=${v}`)) {
+    return `Environment="${assignment.replace(/[\\"]/g, (c) => `\\${c}`)}"`;
+  }
+  return `Environment=${assignment}`;
+}
+
+/**
+ * Build a `systemd --user` unit that runs `nano supervisor __daemon`.
+ * `Restart=on-failure` mirrors the launchd KeepAlive: a crash is restarted, an
+ * intentional `supervisor stop` (clean exit) stays down. `exec`/`entry` and env
+ * values are quoted/escaped so paths or values with whitespace or quotes don't
+ * make systemd misparse the line and fail to start the service.
+ */
+function buildSystemdUserUnit({ exec, entry, env = {} }) {
+  const cmd = `${systemdQuoteExecArg(exec)} ${systemdQuoteExecArg(entry)} nano supervisor __daemon`;
+  const envLines = Object.entries(env)
+    .filter(([, v]) => v != null && v !== '')
+    .map(([k, v]) => systemdEnvLine(k, v))
+    .join('\n');
+  return `[Unit]
+Description=c8ctl nano worker supervisor
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${cmd}
+${envLines}
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+/** Whether a persistent supervisor service is installed for this state home. */
+function supervisorServiceInstalled(platform = osPlatform()) {
+  if (platform === 'darwin') return existsSync(launchAgentPlistPath());
+  if (platform === 'linux') return existsSync(systemdUserUnitPath());
+  return false;
+}
+
+/**
+ * Pure predicate: should `supervisor start` warn about SSH-logout teardown?
+ * Only macOS over SSH without an installed service is exposed to the wedge.
+ */
+function shouldWarnSshTeardown({
+  platform = osPlatform(),
+  env = process.env,
+  installed = supervisorServiceInstalled(platform),
+} = {}) {
+  return platform === 'darwin' && isSshSession(env) && !installed;
+}
+
+function warnSshTeardown(logger) {
+  logger.warn('⚠ macOS + SSH: this supervisor is bound to your SSH login session.');
+  logger.warn('  When you log out, macOS tears that session down and the fleet WEDGES —');
+  logger.warn('  workers keep showing "running" but stop claiming jobs (the activation');
+  logger.warn('  loop spins on: SDK activateJobs failed: fetch failed).');
+  logger.warn('  Install a session-independent service so it survives logout:');
+  logger.warn('    c8ctl nano supervisor install');
+}
+
+function runLaunchctl(args) {
+  try {
+    const r = spawnSync('launchctl', args, { encoding: 'utf8', timeout: 15_000 });
+    return { code: r.status, stdout: (r.stdout || '').trim(), stderr: (r.stderr || '').trim(), error: r.error };
+  } catch (err) {
+    return { code: null, stdout: '', stderr: '', error: err };
+  }
+}
+
+function runSystemctlUser(args) {
+  try {
+    const r = spawnSync('systemctl', ['--user', ...args], { encoding: 'utf8', timeout: 15_000 });
+    return { code: r.status, stdout: (r.stdout || '').trim(), stderr: (r.stderr || '').trim(), error: r.error };
+  } catch (err) {
+    return { code: null, stdout: '', stderr: '', error: err };
+  }
+}
+
+function systemdUserAvailable() {
+  return runSystemctlUser(['--version']).code === 0;
+}
+
+/**
+ * Stop a running daemon (socket `stop` → SIGTERM → SIGKILL the group), used
+ * before installing a service so the launchd/systemd-owned daemon takes over
+ * the deterministic control socket without a second instance fighting for it.
+ */
+async function stopSupervisorProcess(running) {
+  try { await supervisorRequest({ op: 'stop' }); }
+  catch { try { process.kill(running.pid, 'SIGTERM'); } catch { /* already gone */ } }
+  const deadline = Date.now() + STOP_GRACE_MS + 2_000;
+  while (Date.now() < deadline) {
+    if (!isPidAlive(running.pid)) break;
+    await new Promise((r) => setTimeout(r, 150));
+  }
+  if (isPidAlive(running.pid)) {
+    if (osPlatform() !== 'win32') {
+      try { process.kill(-running.pid, 'SIGKILL'); }
+      catch { try { process.kill(running.pid, 'SIGKILL'); } catch { /* ignore */ } }
+    } else {
+      try { process.kill(running.pid, 'SIGKILL'); } catch { /* ignore */ }
+    }
+  }
+  clearSupervisorState();
+}
+
+async function installSupervisorServiceDarwin(logger) {
+  const uid = process.getuid();
+  const label = supervisorServiceLabel();
+  const plistPath = launchAgentPlistPath();
+  const { exec, entry } = c8ctlInvocation();
+  if (!entry) { logger.error('Cannot resolve the c8ctl entry point to install the service.'); return false; }
+
+  // Hand the socket to the launchd-owned daemon: stop any session-bound one.
+  const running = await liveSupervisor();
+  if (running) {
+    logger.info('Stopping the current session-bound supervisor before installing the service…');
+    await stopSupervisorProcess(running);
+  }
+
+  mkdirSync(dirname(plistPath), { recursive: true });
+  mkdirSync(getSupervisorLogDir(), { recursive: true });
+  const daemonLog = supervisorDaemonLogFile();
+  writeFileSync(plistPath, buildLaunchAgentPlist({
+    label, exec, entry, env: supervisorServiceEnv(), stdoutPath: daemonLog, stderrPath: daemonLog,
+  }));
+
+  runLaunchctl(['bootout', launchdServiceTarget(uid, label)]); // best effort: clear any prior instance
+  const boot = runLaunchctl(['bootstrap', launchdDomainTarget(uid), plistPath]);
+  if (boot.code !== 0 && !/already (loaded|bootstrapped)/i.test(boot.stderr)) {
+    logger.error(`launchctl bootstrap failed: ${boot.stderr || boot.error?.message || 'unknown error'}`);
+    return false;
+  }
+  runLaunchctl(['enable', launchdServiceTarget(uid, label)]);
+  runLaunchctl(['kickstart', '-k', launchdServiceTarget(uid, label)]);
+  logger.info(`Installed LaunchAgent ${label} into ${launchdDomainTarget(uid)}.`);
+  logger.info(`  plist: ${plistPath}`);
+  logger.info('The supervisor now survives SSH logout and restarts at login/reboot.');
+  logger.info('Manage it with: c8ctl nano supervisor status | add | stop | uninstall');
+  return true;
+}
+
+function uninstallSupervisorServiceDarwin(logger) {
+  const uid = process.getuid();
+  const label = supervisorServiceLabel();
+  const plistPath = launchAgentPlistPath();
+  const existed = existsSync(plistPath);
+  runLaunchctl(['bootout', launchdServiceTarget(uid, label)]); // stops + unloads
+  try { if (existed) rmSync(plistPath, { force: true }); } catch { /* best effort */ }
+  clearSupervisorState();
+  if (existed) logger.info(`Removed LaunchAgent ${label}.`);
+  else logger.info('No LaunchAgent was installed for this state home.');
+  return true;
+}
+
+async function installSupervisorServiceLinux(logger) {
+  if (!systemdUserAvailable()) {
+    logger.info('systemd --user is not available on this host.');
+    logger.info('No service is required: the supervisor already detaches with setsid, and under');
+    logger.info('systemd-logind with the default KillUserProcesses=no it survives SSH logout.');
+    return true;
+  }
+  const { exec, entry } = c8ctlInvocation();
+  if (!entry) { logger.error('Cannot resolve the c8ctl entry point to install the service.'); return false; }
+
+  const running = await liveSupervisor();
+  if (running) {
+    logger.info('Stopping the current supervisor before installing the service…');
+    await stopSupervisorProcess(running);
+  }
+
+  const unitPath = systemdUserUnitPath();
+  mkdirSync(dirname(unitPath), { recursive: true });
+  writeFileSync(unitPath, buildSystemdUserUnit({ exec, entry, env: supervisorServiceEnv() }));
+
+  // Enable lingering so the user manager (and the daemon) survive logout even
+  // where KillUserProcesses=yes.
+  const user = process.env.USER || process.env.LOGNAME;
+  try { spawnSync('loginctl', user ? ['enable-linger', user] : ['enable-linger'], { timeout: 10_000 }); }
+  catch { /* best effort */ }
+
+  runSystemctlUser(['daemon-reload']);
+  const en = runSystemctlUser(['enable', '--now', systemdUnitName()]);
+  if (en.code !== 0) { logger.error(`systemctl --user enable failed: ${en.stderr || en.error?.message || 'unknown error'}`); return false; }
+  logger.info(`Installed systemd --user unit ${systemdUnitName()} (enabled + started).`);
+  logger.info(`  unit: ${unitPath}`);
+  logger.info('Lingering is enabled so the fleet survives logout and starts at boot.');
+  logger.info('Manage it with: c8ctl nano supervisor status | add | stop | uninstall');
+  return true;
+}
+
+function uninstallSupervisorServiceLinux(logger) {
+  const unitPath = systemdUserUnitPath();
+  const existed = existsSync(unitPath);
+  if (systemdUserAvailable()) runSystemctlUser(['disable', '--now', systemdUnitName()]);
+  try { if (existed) rmSync(unitPath, { force: true }); } catch { /* best effort */ }
+  if (systemdUserAvailable()) runSystemctlUser(['daemon-reload']);
+  clearSupervisorState();
+  if (existed) logger.info(`Removed systemd --user unit ${systemdUnitName()}.`);
+  else logger.info('No systemd --user unit was installed for this state home.');
+  return true;
+}
+
+async function supervisorInstallCmd() {
+  const logger = getLogger();
+  const plat = osPlatform();
+  if (plat === 'darwin') { await installSupervisorServiceDarwin(logger); return; }
+  if (plat === 'linux') { await installSupervisorServiceLinux(logger); return; }
+  logger.error(`supervisor install is not supported on ${plat}.`);
+}
+
+async function supervisorUninstallCmd() {
+  const logger = getLogger();
+  const plat = osPlatform();
+  if (plat === 'darwin') { uninstallSupervisorServiceDarwin(logger); return; }
+  if (plat === 'linux') { uninstallSupervisorServiceLinux(logger); return; }
+  logger.error(`supervisor uninstall is not supported on ${plat}.`);
+}
+
+/**
+ * Start an already-installed LaunchAgent when it is not running, so a
+ * service-owned start can adopt it. `RunAtLoad` only fires at bootstrap/login and
+ * `KeepAlive` is crash-only, so nothing brings the daemon back after a clean
+ * `supervisor stop` — adopt-only would poll an empty socket and fail. Plain
+ * `kickstart` (never `-k`) is a no-op when the service is up, so a live fleet is
+ * never bounced; a service launchd no longer has loaded is re-bootstrapped from
+ * its plist. `run`/`uid`/`label`/`plistPath` are injectable for deterministic tests.
+ */
+function ensureLaunchAgentStarted(logger, { run = runLaunchctl, uid, label, plistPath } = {}) {
+  const svcUid = uid ?? (typeof process.getuid === 'function' ? process.getuid() : 0);
+  const target = launchdServiceTarget(svcUid, label ?? supervisorServiceLabel());
+  let kick = run(['kickstart', target]);
+  if (kick.code === 0) return true;
+
+  // Not loaded in the domain (a `bootout` without uninstall, or a login that
+  // predated the plist): reload it from disk. `bootstrap`'s own status is not the
+  // verdict — an already-loaded service reports a non-zero "Input/output error" —
+  // so re-enable, kick again, and let that decide.
+  run(['bootstrap', launchdDomainTarget(svcUid), plistPath ?? launchAgentPlistPath()]);
+  run(['enable', target]);
+  kick = run(['kickstart', target]);
+  if (kick.code === 0) return true;
+  logger.warn(`launchctl kickstart failed: ${kick.stderr || kick.error?.message || 'unknown error'}`);
+  return false;
+}
+
+/**
+ * On a macOS `supervisor start`/`attach` over SSH, re-parent the daemon into the
+ * persistent `gui/$UID` launchd domain (via an installed LaunchAgent) so it
+ * survives logout instead of dying with the SSH session. If we cannot (or the
+ * operator opts out with C8CTL_NANO_NO_LAUNCHD), warn loudly and fall through to
+ * the ordinary detached spawn. Returns `true` when a service owns the daemon
+ * (already installed, or just reparented) so the caller adopts it instead of
+ * spawning a competing session-bound daemon; `false` on every non-exposed path
+ * (Linux, a local login, opt-out/failure, or a service that would not start).
+ */
+async function maybeReparentOrWarnOnStart(logger) {
+  if (osPlatform() !== 'darwin') return false;     // Linux already survives logout
+  if (supervisorServiceInstalled()) {
+    // An installed service owns the daemon — but make sure it is actually up
+    // first, or adopt-only would time out on the empty socket a clean stop left.
+    if (await liveSupervisor()) return true;
+    if (ensureLaunchAgentStarted(logger)) return true;
+    logger.warn('The installed supervisor service would not start; falling back to a detached (session-bound) daemon.');
+    return false;
+  }
+  if (!isSshSession()) return false;               // a local login session isn't torn down like SSH
+  if (await liveSupervisor()) return false;        // adopting an existing daemon — nothing to re-parent
+  if (coerceBool(process.env.C8CTL_NANO_NO_LAUNCHD, false)) { warnSshTeardown(logger); return false; }
+  logger.info('macOS + SSH detected — re-parenting the supervisor into the gui launchd domain so it survives logout…');
+  const ok = await installSupervisorServiceDarwin(logger);
+  if (!ok) { warnSshTeardown(logger); return false; }
+  return true; // the launchd service now owns the daemon — adopt it, don't spawn
+}
+
 /** Dispatch the `supervisor` subcommand's action. */
 async function supervisorCommand(req, flags) {
   const action = (req.positional[0] || '').toLowerCase();
@@ -9689,13 +10198,21 @@ async function supervisorCommand(req, flags) {
       return;
     case '':
     case 'attach': {
-      const state = await startSupervisorDaemon();
+      // Same session-independence policy as `supervisor start`: a bare `attach`
+      // must not spawn a session-bound daemon that an SSH logout wedges.
+      const state = await startSupervisorWithServicePolicy();
       await attachSupervisorConsole(runningSupervisor() || state);
       return;
     }
     case 'start':
       await supervisorStartCmd(req, flags);
       return;
+    case 'install':
+      await supervisorInstallCmd();
+      return;
+    case 'uninstall':
+      await supervisorUninstallCmd();
+      return;
     case 'status':
     case 'list':
     case 'ls':
@@ -9719,7 +10236,7 @@ async function supervisorCommand(req, flags) {
       supervisorLogsCmd(req);
       return;
     default:
-      getLogger().error(`Unknown supervisor action "${action}". Use: start|status|add|remove|restart|stop|logs|attach`);
+      getLogger().error(`Unknown supervisor action "${action}". Use: start|install|uninstall|status|add|remove|restart|stop|logs|attach`);
       process.exit(1);
   }
 }
@@ -10513,7 +11030,7 @@ async function workforceStartCmd(req, flags, manifestName) {
     process.exit(1);
   }
 
-  const state = await startSupervisorDaemon();
+  const state = await startSupervisorWithServicePolicy(logger);
   logger.info(`Supervisor daemon running (pid ${state.pid}).`);
   const { reachable, workers: live } = await fetchSupervisorWorkers();
   // A running daemon with an unreachable status socket reports `live: []`, which
@@ -12508,6 +13025,20 @@ export {
   clearSupervisorState,
   getSupervisorSocketPath,
   getSupervisorStateFile,
+  isSshSession,
+  xmlEscape,
+  supervisorServiceLabel,
+  launchAgentPlistPath,
+  systemdUnitName,
+  systemdUserUnitPath,
+  launchdDomainTarget,
+  launchdServiceTarget,
+  supervisorServiceEnv,
+  buildLaunchAgentPlist,
+  buildSystemdUserUnit,
+  supervisorServiceInstalled,
+  shouldWarnSshTeardown,
+  ensureLaunchAgentStarted,
 };
 
 export {
@@ -12588,6 +13119,8 @@ export const metadata = {
         { command: 'c8ctl nano work coder --sandbox docker --image ghcr.io/acme/agent:1', description: 'Run jobs in isolated containers with disk-hygiene reaping' },
         { command: 'NANO_AGENTIC_URL=http://localhost:8080 NANO_AGENTIC_SECRET=<shared-secret> c8ctl nano work reviewer', description: 'Enrol the worker on the app\'s same-port /agentic channel in SECURE mode (same NANO_AGENTIC_SECRET as the server) so it appears live (presence + relay terminals) on the Workforce visibility page' },
         { command: 'c8ctl nano supervisor start --worker reviewer --worker coder', description: 'Start a detached supervisor managing several workers from one terminal' },
+        { command: 'c8ctl nano supervisor install', description: 'Install a session-independent supervisor service (macOS LaunchAgent in gui/$UID; Linux systemd --user + lingering) so the fleet survives SSH logout and returns at login/reboot' },
+        { command: 'c8ctl nano supervisor uninstall', description: 'Remove the installed supervisor service (LaunchAgent / systemd --user unit)' },
         { command: 'c8ctl nano supervisor', description: 'Attach an interactive console to the supervisor (detach with Ctrl-D, leaving it running)' },
         { command: 'c8ctl nano supervisor status', description: 'List supervised workers (state, ENGINE + AGENTIC visibility diagnostics, serviced job / idle, pid, restarts, uptime) without the console' },
         { command: 'c8ctl nano supervisor add decider', description: 'Add a supervised worker (forwarding work flags) to the running supervisor' },
@@ -12832,7 +13365,7 @@ function printUsage() {
   console.log('  c8ctl nano hire [--name <n>] [--rank <r>] [--command <c>] [--arg <switch> ...] [--model <m>] [--capabilities <a,b>] [--sandbox none|docker|podman] [--image <ref>] [--terminal pty|pipe] [--protocol pipe|acp] [--permission yolo|escalate|filter] [--env NAME=VALUE ...] [--list]');
   console.log('  c8ctl nano assign <profileName> <cap[,cap...]> [--name <n>] [--capabilities <a,b>]');
   console.log('  c8ctl nano work <profileName> [--auto [--auto-scope <p>]] [--arg <switch> ...] [--recovery-window <ms>] [--idle-timeout <ms>] [--job-timeout <ms>] [--poll-timeout <ms>] [--job-type <token> ...] [--sandbox none|docker|podman] [--image <ref>] [--env NAME=VALUE ...] [--secret-resolver host] [--min-free-mb <n>] [--clone-timeout <ms>] [--keep-runs] [--stream]');
-  console.log('  c8ctl nano supervisor [start|status|add|remove|restart|stop|logs|attach] ... (manage many workers from one terminal)');
+  console.log('  c8ctl nano supervisor [start|install|uninstall|status|add|remove|restart|stop|logs|attach] ... (manage many workers from one terminal)');
   console.log('  c8ctl nano workforce [add|remove|list|start|status|stop] ... [--manifest <manifest>] (declarative, reusable fleet manifests)');
   console.log('');
   console.log('Subcommands:');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8ctl-plugin-nano",
-  "version": "1.55.1",
+  "version": "1.56.1",
   "type": "module",
   "description": "c8ctl plugin to start, inspect, and stop a local Nano BPM (nanobpmn) cluster",
   "main": "c8ctl-plugin.js",
@@ -21,6 +21,7 @@
   ],
   "files": [
     "c8ctl-plugin.js",
+    "agent-instance.mjs",
     "platforms.mjs",
     "agentic.mjs",
     "agentic-loader-hook.mjs",
@@ -71,12 +72,12 @@
   },
   "optionalDependencies": {
     "node-pty": "^1.0.0",
-    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.55.1",
-    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.55.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.55.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.55.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.55.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.55.1",
-    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.55.1"
+    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.56.1",
+    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.56.1",
+    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.56.1",
+    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.56.1",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.56.1",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.56.1",
+    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.56.1"
   }
 }

package/supervisor-engine.mjs

@@ -140,6 +140,18 @@ function mapJob(raw) {
   }
   const pik = raw.processInstanceKey;
   if (pik !== undefined && pik !== null) job.processInstanceKey = String(pik);
+  // Engine-native AgentInstance attribution (issue #194): the element instance the
+  // AgentInstance correlates on, the element id, and the opaque per-activation
+  // `jobLease` token that lease-gates a `createAgentInstance` for an `external`
+  // agent job (nanobpmn #1099/#1106). These ride opaquely to the runner exactly as
+  // the SDK activation surfaces them; absent for ordinary (non-agent) jobs, in which
+  // case the durable-transcript producer stays inert.
+  const eik = raw.elementInstanceKey;
+  if (eik !== undefined && eik !== null) job.elementInstanceKey = String(eik);
+  const eid = raw.elementId;
+  if (eid !== undefined && eid !== null) job.elementId = String(eid);
+  const lease = raw.jobLease;
+  if (lease !== undefined && lease !== null) job.jobLease = String(lease);
   return job;
 }