c8ctl-plugin-nano 1.18.0 → 1.18.1

package/README.md

@@ -207,6 +207,16 @@ the job with a decremented retry count, and a job that outlives `--job-timeout`
 is killed. Profiles are stored in the plugin's `config.json` (see `c8ctl nano
 config`).
 
+> **Activation lock vs. kill deadline.** `--job-timeout` is the harness *kill*
+> deadline. The broker's job-activation lock is derived as `--job-timeout +
+> --lock-grace` (grace defaults to `120000`ms) so it strictly outlasts the kill:
+> the worker always reports the outcome (complete/fail) before the lock lapses.
+> Without that gap a lock expiring exactly as the harness dies lets the broker
+> re-activate the still-retryable job (a second agent starts) and the stale
+> `fail` is rejected with a 409 "job cannot be failed in the current state".
+> Raising `--job-timeout` alone does **not** fix this — it moves both coupled
+> deadlines together; widen `--lock-grace` (or keep the default) instead.
+
 > **Trust boundary.** The profile `command` is run through a shell so you can
 > write a full invocation (args, pipes, multi-word commands). It is
 > **operator-authored** — only what you put in your own `config.json` is

package/c8ctl-plugin.js

@@ -1478,6 +1478,46 @@ function parseJobTypeFlags(input) {
   return { jobTypes, errors };
 }
 
+/**
+ * The broker job-activation lock must strictly outlast the harness kill
+ * deadline: the worker has to report the outcome (complete/fail) before the lock
+ * lapses, or the broker re-activates the still-retryable job (a second agent
+ * starts) and the stale `fail` is rejected 409 "job cannot be failed in the
+ * current state". So lock = kill + grace. Non-finite or non-positive inputs
+ * fall back to fixed defaults (5m kill / 2m grace). All inputs are coerced to
+ * safe positive integers (positive fractional values floor to at least 1) and
+ * grace is capped so a positive kill always fits and `kill + grace` stays within
+ * the safe-integer range, so the invariant lock > kill holds strictly for every
+ * accepted input — including values at or beyond 2^53 where float addition
+ * would otherwise round `kill + grace` back down to `kill`.
+ *
+ * Returns BOTH derived deadlines from this single computation so the caller
+ * never re-derives (and drifts): `killMs` is the *clamped* harness kill deadline
+ * the caller must actually enforce, and `lockMs` is the broker activation lock.
+ * The caller must use `killMs` — not the raw input — for the harness timeout, or
+ * the lock > kill invariant breaks for large inputs (the raw input can exceed
+ * the clamped `killMs`, and thus reach or exceed `lockMs`).
+ *
+ * @returns {{ killMs: number, lockMs: number }}
+ */
+function deriveJobLockMs(jobTimeoutMs, lockGraceMs) {
+  const MAX = Number.MAX_SAFE_INTEGER;
+  const toSafeMs = (value, fallback) => {
+    // Floor positive fractional values to at least 1 so a sub-millisecond input
+    // (e.g. 0.5) never collapses to a non-positive value.
+    const n = Number.isFinite(value) && value > 0 ? Math.max(1, Math.floor(value)) : fallback;
+    return Math.min(n, MAX);
+  };
+  // Cap grace to MAX - 1 so there is always room for a positive kill while
+  // keeping kill + grace within the safe-integer range.
+  const grace = Math.min(toSafeMs(lockGraceMs, 2 * 60_000), MAX - 1);
+  // Cap kill so kill + grace stays a safe integer and floor it at 1 so the
+  // internal kill is always positive; the sum is then exact and strictly
+  // greater than kill (never equal to it via float rounding).
+  const killMs = Math.max(1, Math.min(toSafeMs(jobTimeoutMs, 5 * 60_000), MAX - grace));
+  return { killMs, lockMs: killMs + grace };
+}
+
 /** A profile name must be a safe, filesystem/token-friendly slug. */
 function isValidProfileName(name) {
   return typeof name === 'string' && /^[a-z0-9][a-z0-9._-]*$/i.test(name);
@@ -2679,6 +2719,17 @@ async function workAgent(req, flags) {
   };
   const maxParallelJobs = intFlag(flags?.['max-parallel'], 1);
   const jobTimeoutMs = intFlag(flags?.['job-timeout'], 5 * 60_000);
+  // The broker's job-activation lock MUST outlast the harness kill deadline: the
+  // worker has to report the outcome (complete/fail) before the lock lapses,
+  // otherwise the broker re-activates the still-retryable job (a second agent
+  // starts) and the stale `fail` is rejected with a 409 "job cannot be failed in
+  // the current state". So lock = harness kill + grace. Raising --job-timeout
+  // alone does not help — it moves both coupled deadlines together.
+  const lockGraceMs = intFlag(flags?.['lock-grace'], 2 * 60_000);
+  // deriveJobLockMs is the single source of truth for both deadlines: the harness
+  // MUST enforce the clamped `jobKillMs` (not the raw --job-timeout), or a very
+  // large --job-timeout would outlive the broker lock and re-break the invariant.
+  const { killMs: jobKillMs, lockMs: jobLockMs } = deriveJobLockMs(jobTimeoutMs, lockGraceMs);
 
   // Sandbox: flag overrides the stored profile default. `none` runs on the host
   // (legacy); `docker`/`podman` run each job in a throwaway labelled container.
@@ -2786,7 +2837,7 @@ async function workAgent(req, flags) {
   if (profileEnvKeys.length > 0) logger.info(`  harness env: ${profileEnvKeys.join(', ')}`);
   const extraNote = extraJobTypes.length > 0 ? ` (${extraJobTypes.length} via --job-type)` : '';
   logger.info(`  listening on ${jobTypes.length} job type(s)${extraNote}: ${jobTypes.join('  ')}`);
-  logger.info(`  max parallel: ${maxParallelJobs}; job timeout: ${jobTimeoutMs}ms`);
+  logger.info(`  max parallel: ${maxParallelJobs}; job timeout: ${jobKillMs}ms; activation lock: ${jobLockMs}ms`);
   logger.info('Polling for work — press Ctrl-C to stop.');
 
   const workers = jobTypes.map((jobType) =>
@@ -2794,7 +2845,7 @@ async function workAgent(req, flags) {
       jobType,
       workerName: `${name}:${jobType}`,
       maxParallelJobs,
-      jobTimeoutMs,
+      jobTimeoutMs: jobLockMs,
       jobHandler: async (job) => {
         logger.info(`[${jobType}] job ${job.jobKey} (instance ${job.processInstanceKey ?? '-'}) → ${buildAgentCommandLine(profile.command, effectiveArgs)}`);
 
@@ -2877,7 +2928,7 @@ async function workAgent(req, flags) {
           } catch { resultDir = null; resultFile = null; }
 
           result = await runAgentJob(profile, job, {
-            timeoutMs: jobTimeoutMs,
+            timeoutMs: jobKillMs,
             envelope,
             sandbox,
             image,
@@ -4358,6 +4409,7 @@ export {
   normalizeStoredProfile,
   jobTypeMatrix,
   parseJobTypeFlags,
+  deriveJobLockMs,
   AGENT_TASK_NS,
   AGENT_RESULT_KEY,
   RESULT_SENTINEL,
@@ -4462,6 +4514,7 @@ export const commands = {
       list: { type: 'boolean', description: 'hire: list existing agent profiles instead of creating one' },
       'max-parallel': { type: 'string', description: 'work: max concurrent jobs per worker (default 1)' },
       'job-timeout': { type: 'string', description: 'work: max harness runtime per job in ms; the spawned process is killed past this (default 300000)' },
+      'lock-grace': { type: 'string', description: 'work: extra ms added to --job-timeout to derive the broker activation lock, so the worker reports before the lock lapses (default 120000)' },
       'job-type': { type: 'string', multiple: true, description: 'work: extra job type to service alongside the rank×capability matrix (repeatable)' },
     },
     handler: async (args, flags) => {
@@ -4606,7 +4659,7 @@ function printUsage() {
   console.log('  c8ctl nano config');
   console.log('  c8ctl nano update [--check]');
   console.log('  c8ctl nano hire [--name <n>] [--rank <r>] [--command <c>] [--arg <switch> ...] [--model <m>] [--capabilities <a,b>] [--sandbox none|docker|podman] [--image <ref>] [--env NAME=VALUE ...] [--list]');
-  console.log('  c8ctl nano work <profileName> [--arg <switch> ...] [--max-parallel <n>] [--job-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 work <profileName> [--arg <switch> ...] [--max-parallel <n>] [--job-timeout <ms>] [--lock-grace <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('');
   console.log('Subcommands:');
   console.log('  start    Spawn an N-node local cluster wired to talk to each other on localhost');
@@ -4649,6 +4702,7 @@ function printUsage() {
   console.log('  --max-parallel <n>   work: max concurrent jobs per worker (default 1)');
   console.log('  --job-type <token>   work: extra job type to service alongside the rank×capability matrix (repeatable)');
   console.log('  --job-timeout <ms>   work: max harness runtime per job in ms (default 300000)');
+  console.log('  --lock-grace <ms>    work: extra ms over --job-timeout for the broker activation lock (default 120000)');
   console.log('  --secret-resolver <r> work: secret resolver for task secretRefs (host; default host)');
   console.log('  --reap-age <ms>      work: age before a finished agent container/workspace is reaped (default 3600000)');
   console.log('  --reap-interval <ms> work: how often to sweep finished agent containers/workspaces (default 300000)');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8ctl-plugin-nano",
-  "version": "1.18.0",
+  "version": "1.18.1",
   "type": "module",
   "description": "c8ctl plugin to start, inspect, and stop a local Nano BPM (nanobpmn) cluster",
   "main": "c8ctl-plugin.js",
@@ -49,12 +49,12 @@
     "semantic-release": "^25.0.3"
   },
   "optionalDependencies": {
-    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.18.0",
-    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.18.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.18.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.18.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.18.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.18.0",
-    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.18.0"
+    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.18.1",
+    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.18.1",
+    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.18.1",
+    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.18.1",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.18.1",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.18.1",
+    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.18.1"
   }
 }