@consensus-tools/consensus-tools 0.1.0 → 0.1.3

package/src/cliConfig.ts

@@ -0,0 +1,97 @@
+import { existsSync, promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export type ConsensusCliConfig = {
+  agentId?: string;
+  activeBoard: 'local' | 'remote';
+  boards: {
+    local: { type: 'local'; root: string; jobsPath: string; ledgerPath: string };
+    remote: { type: 'remote'; url: string; boardId: string; auth: { type: 'apiKey'; apiKeyEnv: string } };
+  };
+  defaults: { policy: string; reward: number; stake: number; leaseSeconds: number };
+};
+
+export const defaultConsensusCliConfig: ConsensusCliConfig = {
+  activeBoard: 'remote',
+  boards: {
+    local: {
+      type: 'local',
+      root: '~/.openclaw/workplace/consensus-board',
+      jobsPath: 'jobs',
+      ledgerPath: 'ledger.json'
+    },
+    remote: {
+      type: 'remote',
+      url: 'https://api.consensus.tools',
+      boardId: 'board_all',
+      auth: { type: 'apiKey', apiKeyEnv: 'CONSENSUS_API_KEY' }
+    }
+  },
+  defaults: {
+    policy: 'HIGHEST_CONFIDENCE_SINGLE',
+    reward: 8,
+    stake: 4,
+    leaseSeconds: 180
+  }
+};
+
+export function expandHome(input: string): string {
+  if (!input.startsWith('~')) return input;
+  return path.join(os.homedir(), input.slice(1));
+}
+
+export function resolveCliConfigPath(cwd: string = process.cwd()): string {
+  const envPath = process.env.CONSENSUS_CONFIG;
+  if (envPath) return expandHome(envPath);
+
+  const local = path.join(cwd, '.consensus', 'config.json');
+  if (existsSync(local)) return local;
+
+  return path.join(os.homedir(), '.consensus', 'config.json');
+}
+
+export async function loadCliConfig(cwd: string = process.cwd()): Promise<ConsensusCliConfig> {
+  const filePath = resolveCliConfigPath(cwd);
+  try {
+    const raw = await fs.readFile(filePath, 'utf8');
+    return JSON.parse(raw) as ConsensusCliConfig;
+  } catch {
+    return JSON.parse(JSON.stringify(defaultConsensusCliConfig)) as ConsensusCliConfig;
+  }
+}
+
+export async function saveCliConfig(config: ConsensusCliConfig, cwd: string = process.cwd()): Promise<void> {
+  const filePath = resolveCliConfigPath(cwd);
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, JSON.stringify(config, null, 2), 'utf8');
+}
+
+export function getConfigValue(config: any, key: string): any {
+  return key.split('.').reduce((acc, part) => (acc ? acc[part] : undefined), config);
+}
+
+export function setConfigValue(config: any, key: string, value: any): void {
+  const parts = key.split('.');
+  let cur = config as any;
+  for (let i = 0; i < parts.length - 1; i += 1) {
+    if (!cur[parts[i]]) cur[parts[i]] = {};
+    cur = cur[parts[i]];
+  }
+  cur[parts[parts.length - 1]] = value;
+}
+
+export function parseValue(input: string): any {
+  try {
+    return JSON.parse(input);
+  } catch {
+    return input;
+  }
+}
+
+export function resolveRemoteBaseUrl(remoteUrl: string, boardId: string): string {
+  const trimmed = remoteUrl.replace(/\/$/, '');
+  if (trimmed.includes('/v1/boards/')) return trimmed;
+  return `${trimmed}/v1/boards/${boardId}`;
+}
+

package/src/config.ts

@@ -50,8 +50,9 @@ export const configSchema = {
                 type: {
                   type: 'string',
                   enum: [
-                    'SINGLE_WINNER',
+                    'FIRST_SUBMISSION_WINS',
                     'HIGHEST_CONFIDENCE_SINGLE',
+                    'APPROVAL_VOTE',
                     'OWNER_PICK',
                     'TOP_K_SPLIT',
                     'MAJORITY_VOTE',
@@ -59,7 +60,7 @@ export const configSchema = {
                     'WEIGHTED_REPUTATION',
                     'TRUSTED_ARBITER'
                   ],
-                  default: 'SINGLE_WINNER'
+                  default: 'FIRST_SUBMISSION_WINS'
                 },
                 trustedArbiterAgentId: { type: 'string', default: '' },
                 minConfidence: { type: 'number', default: 0, minimum: 0, maximum: 1 },
@@ -99,8 +100,9 @@ export const configSchema = {
               type: {
                 type: 'string',
                 enum: [
-                  'SINGLE_WINNER',
+                  'FIRST_SUBMISSION_WINS',
                   'HIGHEST_CONFIDENCE_SINGLE',
+                  'APPROVAL_VOTE',
                   'OWNER_PICK',
                   'TOP_K_SPLIT',
                   'MAJORITY_VOTE',
@@ -190,12 +192,13 @@ export const defaultConfig: ConsensusToolsConfig = {
       maxParticipants: 3,
       minParticipants: 1,
       expiresSeconds: 86400,
-      consensusPolicy: { type: 'SINGLE_WINNER', trustedArbiterAgentId: '' },
+      consensusPolicy: { type: 'FIRST_SUBMISSION_WINS', trustedArbiterAgentId: '', tieBreak: 'earliest' },
       slashingPolicy: { enabled: false, slashPercent: 0, slashFlat: 0 }
     },
     consensusPolicies: {
-      SINGLE_WINNER: { type: 'SINGLE_WINNER' },
+      FIRST_SUBMISSION_WINS: { type: 'FIRST_SUBMISSION_WINS' },
       HIGHEST_CONFIDENCE_SINGLE: { type: 'HIGHEST_CONFIDENCE_SINGLE', minConfidence: 0 },
+      APPROVAL_VOTE: { type: 'APPROVAL_VOTE', quorum: 1, minScore: 1, minMargin: 0, tieBreak: 'earliest', approvalVote: { weightMode: 'equal', settlement: 'immediate' } },
       OWNER_PICK: { type: 'OWNER_PICK' },
       TOP_K_SPLIT: { type: 'TOP_K_SPLIT', topK: 2, ordering: 'confidence' },
       MAJORITY_VOTE: { type: 'MAJORITY_VOTE' },

package/src/initWizard.ts

@@ -0,0 +1,237 @@
+import os from 'node:os';
+import { createInterface, type Interface } from 'node:readline/promises';
+import process from 'node:process';
+import type { ConsensusCliConfig } from './cliConfig';
+import { defaultConsensusCliConfig } from './cliConfig';
+
+export type InitWizardResult = {
+  config: ConsensusCliConfig;
+  // Values are already shell-escaped for `export KEY=<value>` lines.
+  env?: Record<string, string>;
+};
+
+const POLICY_CHOICES = [
+  'HIGHEST_CONFIDENCE_SINGLE',
+  'APPROVAL_VOTE',
+  'TOP_K_SPLIT',
+  'OWNER_PICK',
+  'FIRST_SUBMISSION_WINS',
+  'MAJORITY_VOTE',
+  'WEIGHTED_VOTE_SIMPLE',
+  'WEIGHTED_REPUTATION',
+  'TRUSTED_ARBITER'
+] as const;
+
+function defaultAgentId(): string {
+  const fromEnv = process.env.CONSENSUS_AGENT_ID;
+  if (fromEnv) return fromEnv;
+  let user = 'cli';
+  try {
+    const u = os.userInfo();
+    if (u?.username) user = u.username;
+  } catch {
+    // ignore
+  }
+  return `${user}@${os.hostname()}`;
+}
+
+function shellEscape(value: string): string {
+  // Conservative quoting for bash/zsh.
+  return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\$/g, '\\$').replace(/`/g, '\\`')}"`;
+}
+
+function toNumber(value: string, fallback: number): number {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+function toInt(value: string, fallback: number): number {
+  const n = Number.parseInt(value, 10);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+async function promptLine(rl: Interface, message: string, fallback?: string): Promise<string> {
+  const suffix = fallback ? ` [${fallback}]` : '';
+  const answer = (await rl.question(`${message}${suffix}: `)).trim();
+  return answer || fallback || '';
+}
+
+async function promptConfirm(rl: Interface, message: string, fallback: boolean): Promise<boolean> {
+  const hint = fallback ? 'Y/n' : 'y/N';
+  const answer = (await rl.question(`${message} (${hint}): `)).trim().toLowerCase();
+  if (!answer) return fallback;
+  if (['y', 'yes'].includes(answer)) return true;
+  if (['n', 'no'].includes(answer)) return false;
+  return fallback;
+}
+
+async function promptSelect<T extends string>(
+  rl: Interface,
+  message: string,
+  choices: Array<{ value: T; label: string }>,
+  fallback: T
+): Promise<T> {
+  process.stdout.write(`${message}\n`);
+  for (let i = 0; i < choices.length; i += 1) {
+    const c = choices[i];
+    process.stdout.write(`  ${i + 1}) ${c.label}\n`);
+  }
+  const answer = (await rl.question(`Select [${choices.findIndex((c) => c.value === fallback) + 1}]: `)).trim();
+  if (!answer) return fallback;
+  const idx = Number.parseInt(answer, 10);
+  if (Number.isFinite(idx) && idx >= 1 && idx <= choices.length) {
+    return choices[idx - 1].value;
+  }
+  // Allow direct value entry.
+  const asValue = answer as T;
+  if (choices.some((c) => c.value === asValue)) return asValue;
+  return fallback;
+}
+
+async function promptPassword(message: string): Promise<string> {
+  // Minimal masked input for TTY use. Falls back to visible input if raw mode is unavailable.
+  if (!process.stdin.isTTY || !process.stdout.isTTY || typeof process.stdin.setRawMode !== 'function') {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      return (await rl.question(`${message} (input will be visible): `)).trim();
+    } finally {
+      rl.close();
+    }
+  }
+
+  return await new Promise<string>((resolve) => {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+    let value = '';
+
+    stdout.write(`${message}: `);
+    stdin.setRawMode(true);
+    stdin.resume();
+
+    const cleanup = () => {
+      stdin.setRawMode(false);
+      stdin.pause();
+      stdin.removeListener('data', onData);
+      stdout.write('\n');
+    };
+
+    const onData = (buf: Buffer) => {
+      const s = buf.toString('utf8');
+      if (s === '\r' || s === '\n') {
+        cleanup();
+        resolve(value);
+        return;
+      }
+      if (s === '\u0003') {
+        // Ctrl-C
+        cleanup();
+        process.exit(130);
+      }
+      if (s === '\u007f') {
+        // backspace
+        if (value.length > 0) {
+          value = value.slice(0, -1);
+          stdout.write('\b \b');
+        }
+        return;
+      }
+      // Ignore arrow keys / escape sequences.
+      if (s.startsWith('\u001b')) return;
+      value += s;
+      stdout.write('*');
+    };
+
+    stdin.on('data', onData);
+  });
+}
+
+export async function runInitWizard(rootDir: string): Promise<InitWizardResult> {
+  process.stdout.write(
+    [
+      '+---------------------------------+',
+      '| consensus-tools init wizard     |',
+      '+---------------------------------+',
+      `workspace: ${rootDir}`,
+      ''
+    ].join('\n') + '\n'
+  );
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const mode = await promptSelect<'remote' | 'local'>(
+      rl,
+      'Where should consensus-tools run?',
+      [
+        { value: 'remote', label: 'Hosted board (Recommended)' },
+        { value: 'local', label: 'Local files (shell scripts; limited)' }
+      ],
+      'remote'
+    );
+
+    const cfg: ConsensusCliConfig = JSON.parse(JSON.stringify(defaultConsensusCliConfig));
+    cfg.activeBoard = mode;
+
+    cfg.agentId = await promptLine(rl, 'Default agent id (sent as agentId)', cfg.agentId || defaultAgentId());
+
+    cfg.defaults.policy = await promptSelect<string>(
+      rl,
+      'Default consensus policy',
+      POLICY_CHOICES.map((p) => ({ value: p, label: p })),
+      cfg.defaults.policy
+    );
+
+    cfg.defaults.reward = toNumber(await promptLine(rl, 'Default reward (credits)', String(cfg.defaults.reward)), cfg.defaults.reward);
+    cfg.defaults.stake = toNumber(await promptLine(rl, 'Default stake (credits)', String(cfg.defaults.stake)), cfg.defaults.stake);
+    cfg.defaults.leaseSeconds = toInt(
+      await promptLine(rl, 'Default leaseSeconds', String(cfg.defaults.leaseSeconds)),
+      cfg.defaults.leaseSeconds
+    );
+
+    if (mode === 'remote') {
+      cfg.boards.remote.url = await promptLine(rl, 'Hosted board URL (no trailing /v1/boards)', cfg.boards.remote.url);
+      cfg.boards.remote.boardId = await promptLine(rl, 'Board id', cfg.boards.remote.boardId);
+      cfg.boards.remote.auth.apiKeyEnv = await promptLine(
+        rl,
+        'Env var name for access token',
+        cfg.boards.remote.auth.apiKeyEnv
+      );
+
+      const writeEnv = await promptConfirm(rl, 'Write .consensus/.env now? (do not commit it)', false);
+      if (!writeEnv) return { config: cfg };
+
+      const token = (await promptPassword(`Access token value (${cfg.boards.remote.auth.apiKeyEnv})`)).trim();
+      const env = buildEnv(cfg, token);
+      return { config: cfg, env };
+    }
+
+    cfg.boards.local.root = await promptLine(rl, 'Local board root (used by generated shell scripts)', cfg.boards.local.root);
+    return { config: cfg };
+  } finally {
+    rl.close();
+  }
+}
+
+function buildEnv(cfg: ConsensusCliConfig, token: string): Record<string, string> {
+  const env: Record<string, string> = {};
+  env.CONSENSUS_MODE = cfg.activeBoard === 'remote' ? 'remote' : 'local';
+  env.CONSENSUS_AGENT_ID = cfg.agentId || defaultAgentId();
+
+  env.CONSENSUS_DEFAULT_POLICY = cfg.defaults.policy;
+  env.CONSENSUS_DEFAULT_REWARD = String(cfg.defaults.reward);
+  env.CONSENSUS_DEFAULT_STAKE = String(cfg.defaults.stake);
+  env.CONSENSUS_DEFAULT_LEASE_SECONDS = String(cfg.defaults.leaseSeconds);
+
+  if (cfg.activeBoard === 'remote') {
+    env.CONSENSUS_URL = cfg.boards.remote.url;
+    env.CONSENSUS_BOARD_ID = cfg.boards.remote.boardId;
+    env.CONSENSUS_API_KEY_ENV = cfg.boards.remote.auth.apiKeyEnv || 'CONSENSUS_API_KEY';
+    env[env.CONSENSUS_API_KEY_ENV] = token;
+  } else {
+    env.CONSENSUS_ROOT = cfg.boards.local.root;
+  }
+
+  // Return a map with already-escaped values for direct file emission.
+  const escaped: Record<string, string> = {};
+  for (const [k, v] of Object.entries(env)) escaped[k] = shellEscape(v);
+  return escaped;
+}

package/src/jobs/consensus.ts

@@ -56,7 +56,7 @@ export function resolveConsensus(input: ConsensusInput): ConsensusResult {
     return { winners: [], winningSubmissionIds: [], consensusTrace: { policy, reason: 'no_submissions' }, finalArtifact: null };
   }
 
-  if (policy === 'SINGLE_WINNER') {
+  if (policy === 'FIRST_SUBMISSION_WINS') {
     const sorted = [...input.submissions].sort((a, b) => Date.parse(a.submittedAt) - Date.parse(b.submittedAt));
     const winner = sorted[0];
     return {
@@ -67,6 +67,121 @@ export function resolveConsensus(input: ConsensusInput): ConsensusResult {
     };
   }
 
+  if (policy === 'APPROVAL_VOTE') {
+    const quorum = input.job.consensusPolicy.quorum;
+    const minScore = input.job.consensusPolicy.minScore ?? 1;
+    const minMargin = input.job.consensusPolicy.minMargin ?? 0;
+    const tieBreak = input.job.consensusPolicy.tieBreak ?? 'earliest';
+
+    const weightMode = input.job.consensusPolicy.approvalVote?.weightMode ?? 'equal';
+    const settlement = input.job.consensusPolicy.approvalVote?.settlement ?? 'immediate';
+
+    // Oracle settlement can always be manually finalized by the arbiter, even with no votes.
+    if (settlement === 'oracle' && input.manualWinnerAgentIds && input.manualWinnerAgentIds.length) {
+      return {
+        winners: input.manualWinnerAgentIds,
+        winningSubmissionIds: input.manualSubmissionId ? [input.manualSubmissionId] : [],
+        consensusTrace: { policy, settlement, mode: 'manual' },
+        finalArtifact: findArtifact(input, input.manualSubmissionId)
+      };
+    }
+
+    const scores: Record<string, number> = {};
+    const voteCounts: Record<string, number> = {};
+
+    // Only consider votes that target submissions.
+    const votes = input.votes.filter((v) => v.submissionId || (v.targetType === 'SUBMISSION' && v.targetId));
+    if (quorum && votes.length < quorum) {
+      return {
+        winners: [],
+        winningSubmissionIds: [],
+        consensusTrace: { policy, settlement, reason: 'quorum_not_met', quorum, votes: votes.length },
+        finalArtifact: null
+      };
+    }
+
+    for (const vote of votes) {
+      const sid = vote.submissionId ?? (vote.targetType === 'SUBMISSION' ? vote.targetId : undefined);
+      if (!sid) continue;
+
+      let weight = 1;
+      if (weightMode === 'explicit') weight = vote.weight ?? 1;
+      if (weightMode === 'reputation') weight = input.reputation(vote.agentId);
+
+      // score should be +1 (YES) or -1 (NO); clamp to [-1,1] to avoid weirdness.
+      const s = Math.max(-1, Math.min(1, vote.score ?? 0));
+      scores[sid] = (scores[sid] || 0) + s * weight;
+      voteCounts[sid] = (voteCounts[sid] || 0) + 1;
+    }
+
+    // rank submissions by score desc
+    const ranked = input.submissions
+      .map((sub) => ({ sub, score: scores[sub.id] || 0, votes: voteCounts[sub.id] || 0 }))
+      .sort((a, b) => {
+        if (b.score === a.score) {
+          if (tieBreak === 'confidence') return b.sub.confidence - a.sub.confidence;
+          // default earliest
+          return Date.parse(a.sub.submittedAt) - Date.parse(b.sub.submittedAt);
+        }
+        return b.score - a.score;
+      });
+
+    const best = ranked[0];
+    const second = ranked[1];
+    const margin = second ? best.score - second.score : best.score;
+
+    if (!best || best.votes === 0) {
+      return {
+        winners: [],
+        winningSubmissionIds: [],
+        consensusTrace: { policy, settlement, reason: 'no_votes', scores, voteCounts },
+        finalArtifact: null
+      };
+    }
+
+    if (best.score < minScore || margin < minMargin) {
+      return {
+        winners: [],
+        winningSubmissionIds: [],
+        consensusTrace: { policy, settlement, reason: 'threshold_not_met', minScore, minMargin, best: best.score, margin, scores, voteCounts },
+        finalArtifact: null
+      };
+    }
+
+    if (settlement === 'oracle' || tieBreak === 'arbiter') {
+      // Oracle / arbiter settlement: allow manual finalization, otherwise provide a recommendation.
+      if (input.manualWinnerAgentIds && input.manualWinnerAgentIds.length) {
+        return {
+          winners: input.manualWinnerAgentIds,
+          winningSubmissionIds: input.manualSubmissionId ? [input.manualSubmissionId] : [],
+          consensusTrace: {
+            policy,
+            settlement,
+            mode: 'manual',
+            recommendedSubmissionId: best.sub.id,
+            recommendedAgentId: best.sub.agentId,
+            scores,
+            voteCounts
+          },
+          finalArtifact: findArtifact(input, input.manualSubmissionId)
+        };
+      }
+      return {
+        winners: [],
+        winningSubmissionIds: [],
+        consensusTrace: { policy, settlement, mode: 'awaiting_oracle', recommendedSubmissionId: best.sub.id, recommendedAgentId: best.sub.agentId, scores, voteCounts },
+        finalArtifact: null
+      };
+    }
+
+    return {
+      winners: [best.sub.agentId],
+      winningSubmissionIds: [best.sub.id],
+      consensusTrace: { policy, settlement, scores, voteCounts, minScore, minMargin, tieBreak },
+      finalArtifact: best.sub.artifacts
+    };
+  }
+
   if (policy === 'HIGHEST_CONFIDENCE_SINGLE') {
     const minConfidence = input.job.consensusPolicy.minConfidence ?? 0;
     const sorted = [...input.submissions]

package/src/jobs/engine.ts

@@ -297,11 +297,13 @@ export class JobEngine {
   async vote(agentId: string, jobId: string, input: VoteInput): Promise<Vote> {
     const now = nowIso();
     return (await this.storage.update((state) => {
+      // optional: stake on votes (APPROVAL_VOTE staked settlement)
+      const stakeAmount = input.stakeAmount ? Math.max(0, Number(input.stakeAmount)) : 0;
       const job = state.jobs.find((j) => j.id === jobId);
       if (!job) throw new Error(`Job not found: ${jobId}`);
       if (
         job.mode === 'SUBMISSION' &&
-        (job.consensusPolicy.type === 'SINGLE_WINNER' ||
+        (job.consensusPolicy.type === 'FIRST_SUBMISSION_WINS' ||
           job.consensusPolicy.type === 'HIGHEST_CONFIDENCE_SINGLE' ||
           job.consensusPolicy.type === 'OWNER_PICK' ||
           job.consensusPolicy.type === 'TOP_K_SPLIT' ||
@@ -309,6 +311,22 @@ export class JobEngine {
       ) {
         throw new Error('Voting not enabled for this job');
       }
+
+      // optional vote stake (only meaningful for APPROVAL_VOTE settlement=staked)
+      if (stakeAmount > 0) {
+        const currentBalance = getBalance(state.ledger, agentId);
+        const nextBalance = currentBalance - Math.abs(stakeAmount);
+        ensureNonNegative(nextBalance, `${agentId} vote stake for ${jobId}`);
+        state.ledger.push({
+          id: newId('ledger'),
+          at: now,
+          type: 'STAKE',
+          agentId,
+          amount: -Math.abs(stakeAmount),
+          jobId,
+          reason: 'vote'
+        });
+      }
       const targetType = input.targetType ?? (input.submissionId ? 'SUBMISSION' : input.choiceKey ? 'CHOICE' : undefined);
       const targetId = input.targetId ?? input.submissionId;
       if (targetType === 'SUBMISSION') {
@@ -330,7 +348,7 @@ export class JobEngine {
         agentId,
         score,
         weight: input.weight ?? score,
-        stakeAmount: input.stakeAmount,
+        stakeAmount: stakeAmount || undefined,
         rationale: input.rationale,
         createdAt: now
       };
@@ -359,10 +377,28 @@ export class JobEngine {
         if (arbiter && arbiter !== agentId) {
           throw new Error('Only the trusted arbiter can resolve this job');
         }
+        if (!input.manualWinners || input.manualWinners.length === 0) {
+          throw new Error('Trusted arbiter must provide manual winners to resolve');
+        }
       }
 
-      if (job.consensusPolicy.type === 'OWNER_PICK' && job.createdByAgentId !== agentId) {
-        throw new Error('Only the job creator can resolve this job');
+      if (job.consensusPolicy.type === 'OWNER_PICK') {
+        if (job.createdByAgentId !== agentId) {
+          throw new Error('Only the job creator can resolve this job');
+        }
+        if (!input.manualWinners || input.manualWinners.length === 0) {
+          throw new Error('Owner must provide manual winners to resolve');
+        }
+      }
+
+      if (job.consensusPolicy.type === 'APPROVAL_VOTE' && job.consensusPolicy.approvalVote?.settlement === 'oracle') {
+        const arbiter = job.consensusPolicy.trustedArbiterAgentId;
+        if (arbiter && arbiter !== agentId) {
+          throw new Error('Only the trusted arbiter can resolve this job');
+        }
+        if (!input.manualWinners || input.manualWinners.length === 0) {
+          throw new Error('Oracle settlement requires manual winners to resolve');
+        }
       }
 
       const submissions = state.submissions.filter((s) => s.jobId === jobId);
@@ -398,6 +434,41 @@ export class JobEngine {
         }
       }
 
+      // Vote-stake settlement for APPROVAL_VOTE (best-effort, local-first)
+      if (job.consensusPolicy.type === 'APPROVAL_VOTE' && job.consensusPolicy.approvalVote?.settlement === 'staked') {
+        const winnerSubmissionId = consensus.winningSubmissionIds?.[0];
+        const voteSlashPercent = Math.max(0, Math.min(1, job.consensusPolicy.approvalVote?.voteSlashPercent ?? 0));
+        for (const v of votes) {
+          const st = v.stakeAmount ?? 0;
+          if (!st || st <= 0) continue;
+
+          // Return stake by default
+          state.ledger.push({
+            id: newId('ledger'),
+            at: now,
+            type: 'UNSTAKE',
+            agentId: v.agentId,
+            amount: st,
+            jobId,
+            reason: 'vote'
+          });
+
+          // Slash if vote is "wrong" relative to winner.
+          // Wrong = YES on non-winner OR NO on winner.
+          const votedSubmissionId = v.submissionId ?? (v.targetType === 'SUBMISSION' ? v.targetId : undefined);
+          const isYes = (v.score ?? 0) > 0;
+          const isNo = (v.score ?? 0) < 0;
+          const wrong =
+            (winnerSubmissionId && votedSubmissionId && votedSubmissionId !== winnerSubmissionId && isYes) ||
+            (winnerSubmissionId && votedSubmissionId && votedSubmissionId === winnerSubmissionId && isNo);
+
+          if (wrong && voteSlashPercent > 0) {
+            const slashAmount = Math.min(st, st * voteSlashPercent);
+            slashes.push({ agentId: v.agentId, amount: slashAmount, reason: 'vote_wrong' });
+          }
+        }
+      }
+
       const submissionAgents = new Set(submissions.map((s) => s.agentId));
       for (const bid of bids) {
         const stakeAmount = bid.stakeAmount;