What causes "--watch needs a positive seconds value" in affaan-m/ECC?

Pass a positive integer, e.g. `--watch 30`

--watch needs a positive seconds value

Error message

--watch needs a positive seconds value

What it means

parseArgs in scripts/proximity-tick.js handles the --watch flag by parsing the next argv token as an integer with Number.parseInt; it throws this error when the value is absent, non-numeric, or not a positive integer. This ensures the watch interval is a usable number of seconds before the loop starts.

Solutions

Pass a positive integer, e.g. `--watch 30`
Check shell variables for empty/invalid values before interpolation
Use whole seconds — fractional values are rejected
Ensure --watch is not the last token without a value

Example fix

// before
node scripts/proximity-tick.js --watch
// after
node scripts/proximity-tick.js --watch 30

Defensive patterns

Strategy: validation

Validate before calling

function validateWatchValue(raw) {
  if (raw === undefined || raw.startsWith('--')) return false;
  const n = Number.parseInt(raw, 10);
  return Number.isInteger(n) && n > 0 && String(n) === raw;
}

Type guard

function isPositiveInt(v) {
  return Number.isInteger(v) && v > 0;
}

Try / catch

try {
  await main(process.argv);
} catch (e) {
  if (e.message.includes('--watch needs')) {
    console.error(`${e.message}. Example: --watch 30`);
    process.exitCode = 2;
  } else throw e;
}

Prevention

Always follow --watch with a whole positive number of seconds
Guard interpolated env values: "${WATCH:?positive seconds required}"
Use integers — fractional or negative values are rejected
Don't place --watch as the final argv token without a value

When it happens

Trigger: Running with `--watch` and no following value, a non-integer (`--watch 2.5`), a non-numeric token (`--watch abc`), zero or negative values (`--watch 0`, `--watch -1`), or another flag (`--watch --json`).

Common situations: Forgetting the seconds value at end of argv; interpolating an unset WATCH variable into a shell script; assuming fractional seconds are supported when only integers are.

Understand the failure class

Background: "unknown output mode", "invalid value for flag", "expects true/false": fixing invalid flag value errors in CLI tools — this error's family across 24 libraries.

Related errors

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/f7768eed5f8f8dce. Report an issue: GitHub.

Appendix: source

Thrown at scripts/proximity-tick.js:31

 * Messages are internal ECC agent-to-agent coordination (the ecc2 `messages`
 * table) — not any external channel.
 */

const { resolveControlPaneConfig, buildControlPaneSnapshot } = require('./lib/control-pane/state');
const { createProximityDispatcher, runProximityTick } = require('./lib/control-pane/proximity');
const { createEccMessageSink } = require('./lib/control-pane/message-sink');

function parseArgs(argv) {
  const args = argv.slice(2);
  const parsed = { watchSec: 0, dryRun: false, json: false, help: false, dbPath: null, stateDbPath: null };
  for (let i = 0; i < args.length; i += 1) {
    const a = args[i];
    if (a === '--help' || a === '-h') parsed.help = true;
    else if (a === '--dry-run') parsed.dryRun = true;
    else if (a === '--json') parsed.json = true;
    else if (a === '--watch') {
      const v = Number.parseInt(args[i + 1], 10);
      if (!Number.isInteger(v) || v <= 0) throw new Error('--watch needs a positive seconds value');
      parsed.watchSec = v;
      i += 1;
    } else if (a === '--db') {
      parsed.dbPath = args[i + 1];
      i += 1;
    } else if (a === '--state-db') {
      parsed.stateDbPath = args[i + 1];
      i += 1;
    } else {
      throw new Error(`Unknown argument: ${a}`);
    }
  }
  return parsed;
}

function showHelp() {
  console.log(
    [

View on GitHub (pinned to 8321021c54)