affaan-m/ECC · error · Error

Canonical session snapshot requires workers

Error message

Canonical session snapshot requires workers[${index}].intent to be an object

What it means

This error indicates a worker entry lacks a valid intent object. The canonical schema requires workers[i].intent to expose objective (string, may be empty) and seedPaths (array of strings), capturing what the worker was asked to do. validateCanonicalSnapshot enforces this before persistence or normalization.

Solutions

Add an intent object with objective (string, can be '') and seedPaths ([] is valid) to the offending worker.
Update the snapshot producer/adapter to always emit intent per worker.
Regenerate the snapshot with the current adapters instead of reusing stale persisted JSON.
Add a unit test asserting validateCanonicalSnapshot passes on every fixture snapshot.

Example fix

// before
worker.intent = undefined;
// after
worker.intent = { objective: 'refactor auth module', seedPaths: ['src/auth/'] };

Defensive patterns

Strategy: validation

Validate before calling

const intentOk = snapshot.workers.every(w => w && w.intent && typeof w.intent === 'object' && typeof w.intent.objective === 'string' && Array.isArray(w.intent.seedPaths));
if (!intentOk) throw new Error('every worker needs intent { objective, seedPaths }');

Type guard

function hasIntent(w) { return !!w && typeof w.intent === 'object' && w.intent !== null && typeof w.intent.objective === 'string' && Array.isArray(w.intent.seedPaths); }

Try / catch

try { persistCanonicalSnapshot(snapshot); } catch (err) { if (String(err.message).includes('.intent to be an object')) { console.error('Worker missing intent block:', err.message); /* attach intent scaffold and retry */ } else { throw err; } }

Prevention

Create workers with an intent scaffold even when the objective is empty ('' is allowed).
Derive intent from task data at spawn time, not lazily on first write.
Validate the snapshot before persisting to catch schema drift early.
Keep test fixtures updated with the current canonical schema.

When it happens

Trigger: Calling persistCanonicalSnapshot or a normalize* adapter with a worker whose intent is missing, null, or a non-object (string/number/array).

Common situations: Snapshot builders from older ECC versions that omitted the intent block; test fixtures copied from pre-intent snapshots; a migration script that flattened intent into top-level worker fields.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at scripts/lib/session-adapters/canonical-session.js:216

    ensureString(worker.id, `workers[${index}].id`);
    ensureString(worker.label, `workers[${index}].label`);
    ensureString(worker.state, `workers[${index}].state`);
    ensureString(worker.health, `workers[${index}].health`);
    ensureOptionalString(worker.branch, `workers[${index}].branch`);
    ensureOptionalString(worker.worktree, `workers[${index}].worktree`);

    if (!isObject(worker.runtime)) {
      throw new Error(`Canonical session snapshot requires workers[${index}].runtime to be an object`);
    }

    ensureString(worker.runtime.kind, `workers[${index}].runtime.kind`);
    ensureOptionalString(worker.runtime.command, `workers[${index}].runtime.command`);
    ensureBoolean(worker.runtime.active, `workers[${index}].runtime.active`);
    ensureBoolean(worker.runtime.dead, `workers[${index}].runtime.dead`);

    if (!isObject(worker.intent)) {
      throw new Error(`Canonical session snapshot requires workers[${index}].intent to be an object`);
    }

    ensureStringAllowEmpty(worker.intent.objective, `workers[${index}].intent.objective`);
    ensureArrayOfStrings(worker.intent.seedPaths, `workers[${index}].intent.seedPaths`);

    if (!isObject(worker.outputs)) {
      throw new Error(`Canonical session snapshot requires workers[${index}].outputs to be an object`);
    }

    ensureArrayOfStrings(worker.outputs.summary, `workers[${index}].outputs.summary`);
    ensureArrayOfStrings(worker.outputs.validation, `workers[${index}].outputs.validation`);
    ensureArrayOfStrings(worker.outputs.remainingRisks, `workers[${index}].outputs.remainingRisks`);

    if (!isObject(worker.artifacts)) {
      throw new Error(`Canonical session snapshot requires workers[${index}].artifacts to be an object`);
    }
  });

View on GitHub (pinned to 8321021c54)