c8ctl-plugin-nano 1.44.9 → 1.44.11

package/README.md

@@ -377,6 +377,28 @@ export NANO_AGENTIC_STALE_MS=60000     # force re-discovery if a drop hasn't rec
 export NANO_AGENTIC_WATCHDOG_MS=15000  # how often the watchdog checks channel liveness (default)
 ```
 
+**Lossy-link hardening (reconnect churn that never re-lands presence).** A
+distinct failure mode shows up on a **lossy/roaming WiFi (or NAT) link**: the drop
+*is* detected (an abnormal closure, code `1006`), the client *does* reconnect and
+re-announce — yet presence never re-lands on the hub, so the worker stays absent
+even though its log shows it re-announcing. The sustained-drop watchdog above does
+not catch this, because each brief reconnect keeps resetting its drop clock. Two
+extra safeguards close the gap:
+
+- **Presence-keyed watchdog trigger.** A reconnect only counts as recovered once
+  the socket *holds* for a short grace window (so a `1006` blip that immediately
+  re-drops does not mask an unrecovered presence). When presence has not been
+  confirmed within a threshold — regardless of the reconnect flapping — the
+  watchdog forces the same full re-discovery + reopen.
+- **Jittered reconnect backoff.** Reconnect attempts are spread with equal-jitter
+  backoff so a fleet dropped on the same link does not reconnect in lockstep and
+  re-congest it.
+
+```bash
+export NANO_AGENTIC_PRESENCE_STALE_MS=60000  # force re-discovery if presence isn't re-confirmed within 60s (default)
+export NANO_AGENTIC_PRESENCE_GRACE_MS=5000   # how long a reconnect must hold before presence counts as landed (default)
+```
+
 **Secure mode (opt-in).** For a deployment where you want the visibility channel
 authenticated (rather than open on the LAN), start the server **and** every worker
 box with the **same** `NANO_AGENTIC_SECRET` — same env-var name, same value on both

package/c8ctl-plugin.js

@@ -2587,6 +2587,135 @@ const SANDBOXES = ['none', 'docker', 'podman'];
 // Only container-based sandboxes need an image / disk hygiene / a runtime bin.
 const CONTAINER_SANDBOXES = new Set(['docker', 'podman']);
 
+// Result-nudge (#678). A weak / non-Claude agent can finish a result-contract
+// job (exit 0, real work done) yet never emit the machine-readable result — the
+// downstream gateway then falls through to its default (e.g. a completed review
+// silently re-waits instead of converging). Rather than accept the empty result,
+// give the agent exactly ONE bounded "emit your result now" turn, feeding back
+// its own prior output, in the SAME workspace. This never redoes work; it only
+// recovers a dropped result. Bounded independently of the main run so a second
+// hang can't double a long idle window.
+const NUDGE_IDLE_TIMEOUT_MS = 120_000;
+const NUDGE_HARD_CAP_MS = 300_000;
+// Cap the prior transcript we echo back so a huge run can't blow the nudge prompt.
+// This is a UTF-16 code-unit (character) cap, not a byte cap: `String.slice`
+// counts code units, so with multi-byte output the byte size may be larger.
+const NUDGE_CONTEXT_CAP_CHARS = 24_000;
+
+// The bespoke prompt for the re-emit turn: derive the status from the work the
+// agent already did, write ONLY the result, change nothing else.
+function buildResultNudgePrompt(priorStdout, { hasResultFile = true } = {}) {
+  const ctx = typeof priorStdout === 'string' ? priorStdout.slice(-NUDGE_CONTEXT_CAP_CHARS) : '';
+  const intro = [
+    'You already completed the task in your previous turn, but you did NOT emit a',
+    'machine-readable result, so the orchestrator cannot read your status and the',
+    'run cannot advance.',
+    '',
+    'Do NOT redo the work, re-run tools, edit files, push, or open/modify a PR. Just',
+    'emit the result for the work you already did: a single flat JSON object of your',
+    'result variables (at minimum {"status":"..."}).',
+    '',
+  ];
+  // When the harness could not create the result file, AGENT_RESULT_FILE is NOT
+  // exported (runAgentJob only sets it for a truthy resultFile), so the usual
+  // "write to $AGENT_RESULT_FILE" instruction is impossible. Lead with the stdout
+  // sentinel in that case so weaker agents don't waste the turn chasing an unset
+  // env var; otherwise keep the file the primary path with the sentinel fallback.
+  const how = hasResultFile
+    ? [
+        'Write it to the file named by the AGENT_RESULT_FILE environment variable, e.g.:',
+        '',
+        '    printf \'%s\' \'{"status":"...","summary":"..."}\' > "$AGENT_RESULT_FILE"',
+        '',
+        'If you truly cannot write that file, print exactly one line: ::nano:result:: {json}',
+      ]
+    : [
+        'The AGENT_RESULT_FILE environment variable is unset/empty in this run, so you',
+        'CANNOT write a result file. Instead, print exactly one line to stdout:',
+        '',
+        '    ::nano:result:: {"status":"...","summary":"..."}',
+      ];
+  return [
+    ...intro,
+    ...how,
+    '',
+    'Your previous output (reference — derive the status/summary from it):',
+    '-----',
+    ctx,
+  ].join('\n');
+}
+
+// Given a finished agent run, decide whether it dropped its result and, if so,
+// perform ONE re-emit nudge via the injected `rerun(nudgeText)` (which re-invokes
+// the agent in the same workspace, writing to the same AGENT_RESULT_FILE).
+// `rerun` is injected so this is unit-testable without a real model. Returns the
+// (possibly appended) stdout and whether a nudge was attempted; the caller reads
+// the structured result from the result file / stdout afterwards as usual.
+// Cap a string to MAX_CAPTURE_BYTES of UTF-8 keeping the TAIL (so a trailing
+// `::nano:result::` sentinel / fenced JSON block survives the trim) and skipping
+// any partial leading continuation byte so we start on a char boundary. Mirrors
+// the per-stream capture cap for the nudge's post-concatenation stdout. Returns
+// `{ text, truncated }`.
+function capStdoutTail(s) {
+  const buf = Buffer.from(s, 'utf8');
+  if (buf.length <= MAX_CAPTURE_BYTES) return { text: s, truncated: false };
+  let start = buf.length - MAX_CAPTURE_BYTES;
+  while (start < buf.length && (buf[start] & 0xc0) === 0x80) start += 1;
+  return { text: buf.subarray(start).toString('utf8'), truncated: true };
+}
+
+async function resolveAgentResultWithNudge({ result, resultFile, rerun, logger, logPrefix = '' }) {
+  const stdout0 = result && typeof result.stdout === 'string' ? result.stdout : '';
+  // A parsed result only counts as usable if it still carries at least one
+  // *effective* var after sanitizeResultVars strips the reserved / io.nanobpm.* /
+  // proto keys. An empty `{}` or a reserved-keys-only object leaves downstream
+  // gateways with no status/decision vars — exactly the dropped-result case the
+  // nudge exists to recover — so gate on effective vars, not raw object presence.
+  const hasUsableResult = (parsed) => Object.keys(sanitizeResultVars(parsed)).length > 0;
+  const already = readAgentResultFile(resultFile) ?? parseResultFromStdout(stdout0);
+  // Only nudge a clean run that produced NO usable result but DID produce output
+  // (silence means a crash/hang the idle path already handles, not a dropped result).
+  // A null `resultFile` (temp-dir creation failed) is NOT a reason to skip: the
+  // read-back already falls through to `parseResultFromStdout`, and the nudge
+  // prompt explicitly offers the `::nano:result::` stdout sentinel, so recovery
+  // still works in stdout-sentinel-only mode.
+  if (hasUsableResult(already) || !result?.ok || !stdout0.trim() || typeof rerun !== 'function') {
+    // No nudge: `stdout0` is the incoming stdout verbatim, so keep the returned
+    // `truncated` flag consistent with it — echo the incoming `result.truncated`
+    // rather than hardcoding false, so callers that trust the return value don't
+    // see an already-truncated stdout reported as untruncated.
+    return { stdout: stdout0, nudged: false, truncated: result?.truncated === true };
+  }
+  let nudge = null;
+  let nudgeError = null;
+  try { nudge = await rerun(buildResultNudgePrompt(stdout0, { hasResultFile: resultFile != null })); } catch (err) { nudge = null; nudgeError = err; }
+  const nudgeOut = nudge && typeof nudge.stdout === 'string' ? nudge.stdout : '';
+  // Re-apply the per-stream capture cap after concatenation: `result.stdout` is
+  // forwarded verbatim into the job vars (`output`) and the audit envelope, so
+  // the nudge must not let the combined output bypass MAX_CAPTURE_BYTES. Keep the
+  // tail so a `::nano:result::` sentinel emitted by the nudge survives the trim,
+  // and surface truncation so `result.truncated` stays honest.
+  const capped = capStdoutTail(nudgeOut ? `${stdout0}\n${nudgeOut}` : stdout0);
+  const stdout = capped.text;
+  // The returned `stdout` still starts with `stdout0`, so if the FIRST turn was
+  // already truncated the returned output is truncated regardless of whether the
+  // post-concatenation cap trimmed anything: an empty/short nudge leaves
+  // `capped.truncated` false even though `stdout0` was clipped. OR in the incoming
+  // flag so `truncated` stays consistent with the returned stdout (and with the
+  // no-nudge early return above).
+  const truncated = result?.truncated === true || capped.truncated;
+  const recovered = hasUsableResult(readAgentResultFile(resultFile) ?? parseResultFromStdout(stdout));
+  if (nudgeError && logger?.warn) {
+    logger.warn(`${logPrefix} re-emit nudge rerun threw — ${nudgeError?.message ?? nudgeError}`);
+  }
+  if (logger?.info) {
+    logger.info(recovered
+      ? `${logPrefix} no result on the first turn — recovered it via one re-emit nudge`
+      : `${logPrefix} no result on the first turn — re-emit nudge did not recover one`);
+  }
+  return { stdout, nudged: true, truncated };
+}
+
 function coerceBool(v, dflt = false) {
   if (typeof v === 'boolean') return v;
   if (v == null) return dflt;
@@ -5159,6 +5288,31 @@ function buildAgentPayload(profile, job, envelope) {
   };
 }
 
+// Build the exact bytes handed to the harness on stdin for a run (#678).
+//
+// Normal run: the JSON job envelope from `buildAgentPayload`. Every non-ACP
+// harness (pipe/PTY/container) reads that JSON off stdin, so the shape is a
+// contract — a re-emit nudge must NOT replace it with a bare string or the
+// harness fails to parse its job. So when a `nudgePayload` (the bounded "re-emit
+// your result" prompt) is present:
+//   - ACP delivers stdin verbatim as the `session/prompt` text, so it takes the
+//     raw nudge string.
+//   - Non-ACP keeps the JSON envelope and overrides its prompt fields (top-level
+//     `prompt` and the reserved `task.task.prompt`, i.e. `envelope.task.prompt`)
+//     so a harness that dispatches on either sees the nudge. The shared envelope
+//     is copied, never mutated.
+function buildAgentStdin(profile, job, envelope, { nudgePayload = null, acp = false } = {}) {
+  if (nudgePayload == null) return JSON.stringify(buildAgentPayload(profile, job, envelope));
+  const nudgeText = String(nudgePayload);
+  if (acp) return nudgeText;
+  const base = buildAgentPayload(profile, job, envelope);
+  base.prompt = nudgeText;
+  if (isPlainObject(base.task) && isPlainObject(base.task.task)) {
+    base.task = { ...base.task, task: { ...base.task.task, prompt: nudgeText } };
+  }
+  return JSON.stringify(base);
+}
+
 function baseAgentEnv(profile, job) {
   return {
     AGENT_PROFILE: profile.name,
@@ -5254,10 +5408,17 @@ function startLockExtender(job, windowMs, intervalMs, tag, logger) {
  * 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 } = 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;
   // #110: `protocol`/`permission` drive the ACP executor branch below. The
   // pipe/PTY paths are unchanged, so `protocol === 'pipe'` behaviour is identical.
-  const payload = JSON.stringify(buildAgentPayload(profile, job, envelope));
+  // A `nudgePayload` (#678) carries the bespoke "re-emit your result" prompt for a
+  // bounded second turn in the SAME workspace; everything else (env, cwd, command,
+  // result file) is identical to the main run. ACP delivers stdin as the prompt
+  // text so it takes the raw nudge; every non-ACP harness reads the JSON envelope
+  // off stdin, so there we keep the envelope and override its prompt fields
+  // (buildAgentStdin). Container sandboxes ignore `protocol` (pipe-only today).
+  const acpStdin = protocol === 'acp' && !CONTAINER_SANDBOXES.has(sandbox);
+  const payload = buildAgentStdin(profile, job, envelope, { nudgePayload, acp: acpStdin });
   const agentEnv = baseAgentEnv(profile, job);
   // The harness command line: the profile command plus its structured switches
   // (persisted `--arg`s, possibly extended at work time via opts.args), each
@@ -6098,6 +6259,20 @@ async function rediscoverAgenticUntilConnected({
 // client lib alone. Overridable via NANO_AGENTIC_STALE_MS / NANO_AGENTIC_WATCHDOG_MS.
 const DEFAULT_AGENTIC_STALE_MS = 60_000;
 const DEFAULT_AGENTIC_WATCHDOG_INTERVAL_MS = 15_000;
+// #147 presence-keyed staleness. #144's stale trigger keys on a SUSTAINED socket
+// drop (`disconnectedSince` ages past the threshold). On a lossy WiFi/NAT link
+// that drops `1006` repeatedly, the client lib reconnects and re-announces, but
+// each brief reconnect clears the drop clock — so the sustained-drop trigger
+// never fires even though presence never actually re-lands on the hub (the
+// worker stays absent from the Workers view). The presence-keyed trigger closes
+// that gap: a connection only counts as "presence confirmed" once it HOLDS for
+// the grace window, so a reconnect that immediately re-drops cannot mask an
+// unrecovered presence. When presence has not been confirmed within the stale
+// threshold — regardless of transient reconnect flapping — the watchdog forces a
+// full re-discovery + reopen. Overridable via NANO_AGENTIC_PRESENCE_STALE_MS /
+// NANO_AGENTIC_PRESENCE_GRACE_MS.
+const DEFAULT_AGENTIC_PRESENCE_STALE_MS = DEFAULT_AGENTIC_STALE_MS;
+const DEFAULT_AGENTIC_PRESENCE_GRACE_MS = 5_000;
 
 /**
  * Decide whether a worker's agentic channel is *stale* — i.e. it once connected,
@@ -6132,6 +6307,78 @@ function agenticChannelIsStale({
   return now() - since >= staleAfterMs;
 }
 
+/**
+ * Decide whether a worker's agentic channel is *presence-stale* (#147) — i.e. it
+ * once connected but its presence has NOT been re-confirmed on the hub within
+ * `staleAfterMs`, even though the socket may be intermittently reconnecting. This
+ * is the churn counterpart to {@link agenticChannelIsStale}: on a lossy link the
+ * client lib reconnects and re-announces after every `1006`, which keeps clearing
+ * the sustained-drop clock, so the socket-keyed trigger never fires — yet
+ * presence never actually lands. `presenceHealthySince` is the epoch-ms of the
+ * last time the channel was observed *stably* connected long enough for presence
+ * to be considered landed. The first open seeds it immediately (that open drains
+ * the buffered REGISTER, so presence lands with it); thereafter it advances only
+ * once a connection has *held* past a grace window (via `onPresenceHealthy`), so a
+ * reconnect that immediately re-drops does not count. Pure so the trigger is
+ * unit-testable
+ * without timers or sockets. A channel that never opened is not presence-stale
+ * (the initial connect owns it); a null `presenceHealthySince` (never confirmed,
+ * or reset by a heal) also reads as not-stale so a fresh open is given its grace.
+ *
+ * @param {{
+ *   everConnected: () => boolean,
+ *   presenceHealthySince?: () => (number|null),
+ *   now?: () => number,
+ *   staleAfterMs?: number,
+ * }} opts
+ * @returns {boolean}
+ */
+function agenticPresenceIsStale({
+  everConnected,
+  presenceHealthySince,
+  now = () => Date.now(),
+  staleAfterMs = DEFAULT_AGENTIC_PRESENCE_STALE_MS,
+}) {
+  if (typeof everConnected !== 'function') return false;
+  if (!everConnected()) return false; // never opened → the initial connect owns it
+  const since = typeof presenceHealthySince === 'function' ? presenceHealthySince() : null;
+  if (since == null) return false; // never confirmed / freshly reset → give the open its grace
+  return now() - since >= staleAfterMs;
+}
+
+/**
+ * Equal-jitter backoff (#147). Given a base backoff `baseMs`, keep half of it and
+ * randomise the other half: `baseMs/2 + rand()*baseMs/2`. A fleet of workers that
+ * all dropped on the same lossy link would otherwise reconnect in lockstep (the
+ * client lib's exponential backoff is deterministic), re-congesting the link and
+ * re-triggering the `1006` drops that stranded them. Spreading the reconnect
+ * attempts bounds that thundering-herd churn while preserving the exponential
+ * growth of the underlying policy. Pure (`rand` injectable) so it is testable.
+ *
+ * @param {number} baseMs the deterministic backoff the client lib computed
+ * @param {{ rand?: () => number }} [opts]
+ * @returns {number} the jittered delay in ms (0 when baseMs is non-positive)
+ */
+function jitteredDelay(baseMs, { rand = Math.random } = {}) {
+  const b = Number.isFinite(baseMs) && baseMs > 0 ? baseMs : 0;
+  if (b === 0) return 0;
+  const half = b / 2;
+  return Math.round(half + rand() * half);
+}
+
+/**
+ * Build a reconnect `schedule` function that applies {@link jitteredDelay} to the
+ * backoff the client lib passes, so the worker's reconnect attempts on a lossy
+ * link are de-synchronised (#147). Drops straight into `createWorkChannel`'s
+ * injectable `schedule` seam; the timer is injectable for tests.
+ *
+ * @param {{ rand?: () => number, timer?: (fn: () => void, ms: number) => any }} [opts]
+ * @returns {(fn: () => void, ms: number) => void}
+ */
+function makeJitteredReconnectSchedule({ rand = Math.random, timer = setTimeout } = {}) {
+  return (fn, ms) => { timer(fn, jitteredDelay(ms, { rand })); };
+}
+
 /**
  * Start the worker-side agentic-channel liveness watchdog (#144). On a fixed
  * interval it asks {@link agenticChannelIsStale} whether the channel dropped and
@@ -6149,9 +6396,23 @@ function agenticChannelIsStale({
  * prevent a stale-channel resurrection mid-teardown), and `tick()` runs a single
  * check (tests drive it directly).
  *
+ * #147 adds a second, presence-keyed trigger alongside the #144 sustained-drop
+ * one: each tick, a channel observed *stably* connected (connected for at least
+ * `presenceGraceMs` since `connectedSince()`) advances the presence-health clock
+ * via `onPresenceHealthy()`; when presence has not been confirmed within
+ * `presenceStaleAfterMs` — even while the socket flaps `1006` reconnects — the
+ * watchdog heals just as it does for a sustained drop. The presence accessors are
+ * optional: omitting them leaves the #147 trigger inert, so the #144 behaviour is
+ * unchanged.
+ *
  * @param {{
  *   getChannel: () => (import('./work-channel.mjs').WorkChannel | null),
  *   disconnectedSince: () => (number|null),
+ *   connectedSince?: () => (number|null),
+ *   presenceHealthySince?: () => (number|null),
+ *   onPresenceHealthy?: () => void,
+ *   presenceGraceMs?: number,
+ *   presenceStaleAfterMs?: number,
  *   onStale: () => (void|Promise<void>),
  *   staleAfterMs?: number,
  *   intervalMs?: number,
@@ -6166,6 +6427,11 @@ function startAgenticChannelWatchdog({
   getChannel,
   disconnectedSince,
   onStale,
+  connectedSince = null,
+  presenceHealthySince = null,
+  onPresenceHealthy = null,
+  presenceGraceMs = DEFAULT_AGENTIC_PRESENCE_GRACE_MS,
+  presenceStaleAfterMs = DEFAULT_AGENTIC_PRESENCE_STALE_MS,
   staleAfterMs = DEFAULT_AGENTIC_STALE_MS,
   intervalMs = DEFAULT_AGENTIC_WATCHDOG_INTERVAL_MS,
   now = () => Date.now(),
@@ -6186,17 +6452,39 @@ function startAgenticChannelWatchdog({
   const tick = async () => {
     if (stopped || healing) return; // shutting down, or a heal is in flight — don't stack a second re-discovery
     const ch = typeof getChannel === 'function' ? getChannel() : null;
+    // #147: advance the presence-health clock when the channel is observed
+    // STABLY connected (held for the grace window). A churny link that reconnects
+    // but immediately re-drops never accrues the grace, so its health clock ages
+    // out and the presence-keyed trigger below fires — unlike the sustained-drop
+    // trigger, which the churn keeps resetting. Inert unless the accessors are wired.
+    if (ch && typeof onPresenceHealthy === 'function' && typeof connectedSince === 'function') {
+      try {
+        const cs = connectedSince();
+        if (ch.connected() && cs != null && now() - cs >= presenceGraceMs) onPresenceHealthy();
+      } catch { /* best effort — never let a health probe break the tick */ }
+    }
+    // The channel is stale when EITHER trigger fires: #144's sustained socket
+    // drop, or #147's presence-not-confirmed-despite-reconnect-churn.
+    const stale = !!ch && (
+      agenticChannelIsStale({
+        connected: () => ch.connected(),
+        everConnected: () => ch.everConnected(),
+        disconnectedSince,
+        now,
+        staleAfterMs,
+      })
+      || agenticPresenceIsStale({
+        everConnected: () => ch.everConnected(),
+        presenceHealthySince,
+        now,
+        staleAfterMs: presenceStaleAfterMs,
+      })
+    );
     // No channel object → the initial open or the cold-start self-heal loop owns
     // recovery; the watchdog only guards a channel that HAS connected and stalled.
     // A missing or non-stale (healthy / recovered / still-connecting) channel also
     // ends any current stale episode, so re-arm the latch for the next one.
-    if (!ch || !agenticChannelIsStale({
-      connected: () => ch.connected(),
-      everConnected: () => ch.everConnected(),
-      disconnectedSince,
-      now,
-      staleAfterMs,
-    })) {
+    if (!stale) {
       firedForEpisode = false;
       return;
     }
@@ -6205,9 +6493,16 @@ function startAgenticChannelWatchdog({
     firedForEpisode = true;
     try {
       if (stopped) return; // shutdown raced us between the checks — do not heal
-      const since = disconnectedSince();
-      const downFor = since != null ? Math.round((now() - since) / 1000) : '?';
-      logger?.warn?.(`  agentic channel: no reconnect ${downFor}s after drop — forcing re-discovery (the client lib did not self-heal; likely a half-open drop).`);
+      const since = typeof disconnectedSince === 'function' ? disconnectedSince() : null;
+      // During reconnect churn `disconnectedSince` can be null (no sustained drop)
+      // or reset by the latest blip, so it under-reports the real staleness. Fall
+      // back to the presence-health clock — the signal we actually acted on — so
+      // the logged age reflects how long presence has genuinely been unconfirmed.
+      const staleSince = since != null
+        ? since
+        : (typeof presenceHealthySince === 'function' ? presenceHealthySince() : null);
+      const downFor = staleSince != null ? Math.round((now() - staleSince) / 1000) : '?';
+      logger?.warn?.(`  agentic channel: presence not confirmed within threshold (down ${downFor}s / reconnect churn) — forcing re-discovery (the client lib did not self-heal; likely a lossy-link 1006 churn or half-open drop).`);
       await onStale?.();
     } catch (err) {
       firedForEpisode = false; // heal failed → re-arm so a later tick retries this episode
@@ -6727,6 +7022,16 @@ async function workAgent(req, flags) {
   // shutdown); `agenticSelfHealing` guards against two concurrent re-discovery
   // loops (the cold-start one and a watchdog-triggered one).
   let agenticDisconnectedSince = null;
+  // #147 presence-keyed watchdog state. `agenticConnectedSince` is the epoch-ms
+  // the channel last (re)connected (null while down); the watchdog uses it to
+  // require a stable connection to have held for a grace window before counting
+  // presence as confirmed. `agenticPresenceHealthyAt` is the epoch-ms presence
+  // was last confirmed healthy — advanced on the first connect (buffered REGISTER
+  // drains) and by the watchdog whenever a stable connection is observed, and
+  // reset by a heal. When it ages past the presence-stale threshold — even while
+  // the socket flaps `1006` reconnects — the watchdog forces a re-discovery.
+  let agenticConnectedSince = null;
+  let agenticPresenceHealthyAt = null;
   /** @type {{ stop: () => void } | null} */
   let agenticWatchdog = null;
   let agenticSelfHealing = false;
@@ -6824,6 +7129,11 @@ async function workAgent(req, flags) {
         token: cfg.token,
         credential: cfg.credential,
         bufferCapacity: cfg.bufferCapacity,
+        // #147: de-synchronise reconnect attempts with equal-jitter backoff so a
+        // fleet dropped on the same lossy link does not reconnect in lockstep and
+        // re-congest it. Wraps the client lib's own exponential policy (which has
+        // no jitter of its own); the base delays/factor stay the lib's defaults.
+        schedule: makeJitteredReconnectSchedule(),
         logger,
       });
       const shown = redactAgenticUrl(buildAgenticUrl(cfg.url, {}));
@@ -6843,16 +7153,38 @@ async function workAgent(req, flags) {
       // a disconnect starts it (first drop wins, so the watchdog measures from the
       // ORIGINAL drop, not the latest of a reconnect storm). The watchdog reads
       // this to decide when the client lib has failed to self-heal.
-      workChannel.onConnect(() => { markAgentic('connected'); agenticDisconnectedSince = null; });
-      workChannel.onReconnect(() => { markAgentic('connected'); agenticDisconnectedSince = null; });
+      workChannel.onConnect(() => {
+        markAgentic('connected');
+        agenticDisconnectedSince = null;
+        agenticConnectedSince = Date.now();
+        // First open drains the buffered REGISTER → presence lands; seed the
+        // presence-health clock so the #147 trigger measures from here (#147).
+        agenticPresenceHealthyAt = Date.now();
+      });
+      workChannel.onReconnect(() => {
+        markAgentic('connected');
+        agenticDisconnectedSince = null;
+        agenticConnectedSince = Date.now();
+        // Deliberately do NOT advance agenticPresenceHealthyAt here: a reconnect
+        // only CLAIMS presence (re-announces). On a lossy link the socket may
+        // re-drop `1006` before presence actually lands, so the watchdog confirms
+        // it only once a connection HOLDS for the grace window — a reconnect that
+        // immediately re-drops must not mask an unrecovered presence (#147).
+      });
       workChannel.onDisconnect((info) => {
         markAgentic('disconnected', normalizeAgenticMessage(info));
         if (agenticDisconnectedSince == null) agenticDisconnectedSince = Date.now();
+        agenticConnectedSince = null;
       });
-      if (workChannel.connected()) { markAgentic('connected'); agenticDisconnectedSince = null; }
-      else if (workChannel.everConnected()) {
+      if (workChannel.connected()) {
+        markAgentic('connected');
+        agenticDisconnectedSince = null;
+        agenticConnectedSince = Date.now();
+        if (agenticPresenceHealthyAt == null) agenticPresenceHealthyAt = Date.now();
+      } else if (workChannel.everConnected()) {
         markAgentic('disconnected');
         if (agenticDisconnectedSince == null) agenticDisconnectedSince = Date.now();
+        agenticConnectedSince = null;
       }
     } catch (err) {
       // Never let a channel failure stop the worker from doing its actual job.
@@ -6932,6 +7264,8 @@ async function workAgent(req, flags) {
     if (!stale) return;
     workChannel = null; // re-arms armAgenticSelfHeal()'s shouldContinue gate
     agenticDisconnectedSince = null; // reset the clock; the fresh open restarts it
+    agenticConnectedSince = null; // #147: the fresh open re-seeds it
+    agenticPresenceHealthyAt = null; // #147: the fresh open re-confirms presence
     try { bufferMonitor?.stop(); } catch { /* best effort */ }
     bufferMonitor = null;
     markAgentic('disconnected', 'stale channel — re-discovering hub');
@@ -6945,9 +7279,18 @@ async function workAgent(req, flags) {
     if (agenticWatchdog) return;
     const staleAfterMs = Math.max(5_000, intFlag(process.env.NANO_AGENTIC_STALE_MS, DEFAULT_AGENTIC_STALE_MS));
     const intervalMs = Math.max(1_000, intFlag(process.env.NANO_AGENTIC_WATCHDOG_MS, DEFAULT_AGENTIC_WATCHDOG_INTERVAL_MS));
+    const presenceStaleAfterMs = Math.max(5_000, intFlag(process.env.NANO_AGENTIC_PRESENCE_STALE_MS, DEFAULT_AGENTIC_PRESENCE_STALE_MS));
+    const presenceGraceMs = Math.max(1_000, intFlag(process.env.NANO_AGENTIC_PRESENCE_GRACE_MS, DEFAULT_AGENTIC_PRESENCE_GRACE_MS));
     agenticWatchdog = startAgenticChannelWatchdog({
       getChannel: () => workChannel,
       disconnectedSince: () => agenticDisconnectedSince,
+      // #147: presence-keyed trigger — heal reconnect-churn that never re-lands
+      // presence, not just a sustained socket drop.
+      connectedSince: () => agenticConnectedSince,
+      presenceHealthySince: () => agenticPresenceHealthyAt,
+      onPresenceHealthy: () => { agenticPresenceHealthyAt = Date.now(); },
+      presenceStaleAfterMs,
+      presenceGraceMs,
       onStale: healStaleAgenticChannel,
       staleAfterMs,
       intervalMs,
@@ -7255,7 +7598,7 @@ async function workAgent(req, flags) {
             liveRunDirs.add(resultDir);
           } catch { resultDir = null; resultFile = null; }
 
-          result = await runAgentJob(profile, job, {
+          const runOpts = {
             timeoutMs: effectiveHardCapMs,
             idleTimeoutMs: effectiveIdleTimeoutMs,
             recoveryWindowMs: effectiveRecoveryWindowMs,
@@ -7286,7 +7629,42 @@ 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,
-          });
+          };
+          result = await runAgentJob(profile, job, runOpts);
+
+          // Gap 2 (#678): a clean run that emitted no machine-readable result gets
+          // ONE bounded re-emit nudge in the same workspace, feeding back its own
+          // output, before we accept an empty result. Runs before finalizeGit so
+          // the workspace/result file are still live; the nudge changes no code.
+          // Not gated on `resultFile`: when the temp dir/file could not be created
+          // the result is recoverable only via the stdout `::nano:result::`
+          // sentinel, which `resolveAgentResultWithNudge` handles directly.
+          if (result.ok) {
+            const { stdout, nudged, truncated } = await resolveAgentResultWithNudge({
+              result,
+              resultFile,
+              logger,
+              logPrefix: `[${jobType}] job ${job.jobKey}:`,
+              rerun: (nudgeText) => runAgentJob(profile, job, {
+                ...runOpts,
+                nudgePayload: nudgeText,
+                stream: false,
+                idleTimeoutMs: Math.min(effectiveIdleTimeoutMs || NUDGE_IDLE_TIMEOUT_MS, NUDGE_IDLE_TIMEOUT_MS),
+                // Cap the recovery/probe window to the same 120s idle bound: it is
+                // used by createIdleLivenessMonitor as the probe window when >0, so
+                // inheriting the (possibly minutes-long) `effectiveRecoveryWindowMs`
+                // from runOpts would let a silent nudge run outlive the intended
+                // 120s idle bound and delay convergence on a wedged second turn.
+                recoveryWindowMs: Math.min(effectiveRecoveryWindowMs || NUDGE_IDLE_TIMEOUT_MS, NUDGE_IDLE_TIMEOUT_MS),
+                timeoutMs: Math.min(effectiveHardCapMs || NUDGE_HARD_CAP_MS, NUDGE_HARD_CAP_MS) || NUDGE_HARD_CAP_MS,
+              }),
+            });
+            result.stdout = stdout;
+            if (nudged) {
+              result.nudgedForResult = true;
+              if (truncated) result.truncated = true;
+            }
+          }
 
           // Finalize git only when the harness succeeded — never push a
           // half-finished workspace.
@@ -11958,6 +12336,9 @@ export {
   rediscoverAgenticUntilConnected,
   defaultAgenticRediscoveryDelays,
   agenticChannelIsStale,
+  agenticPresenceIsStale,
+  jitteredDelay,
+  makeJitteredReconnectSchedule,
   startAgenticChannelWatchdog,
 };
 export { compareSemver, githubRepoSlug, filterReleasesSince, renderReleaseBody };
@@ -11991,11 +12372,14 @@ export {
   makeSecretResolver,
   hostEnvSecretResolver,
   buildAgentPayload,
+  buildAgentStdin,
   buildResultEnvelope,
   parseAgentResultObject,
   readAgentResultFile,
   parseResultFromStdout,
   sanitizeResultVars,
+  buildResultNudgePrompt,
+  resolveAgentResultWithNudge,
   parseEnvPairs,
   normalizeEnvMap,
   normalizeArgList,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8ctl-plugin-nano",
-  "version": "1.44.9",
+  "version": "1.44.11",
   "type": "module",
   "description": "c8ctl plugin to start, inspect, and stop a local Nano BPM (nanobpmn) cluster",
   "main": "c8ctl-plugin.js",
@@ -57,12 +57,12 @@
   },
   "optionalDependencies": {
     "node-pty": "^1.0.0",
-    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.44.9",
-    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.44.9",
-    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.44.9",
-    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.44.9",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.44.9",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.44.9",
-    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.44.9"
+    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.44.11",
+    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.44.11",
+    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.44.11",
+    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.44.11",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.44.11",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.44.11",
+    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.44.11"
   }
 }