@consensus-tools/consensus-tools 0.1.2 → 0.1.3

package/README.md

@@ -1,6 +1,6 @@
 # consensus.tools
 
-![consensus-tools](./assets/consensus-tools)
+![consensus-tools](https://cdn.jsdelivr.net/npm/@consensus-tools/consensus-tools@latest/assets/consensus-tools.png)
 
 **High-confidence decisions for agentic systems.**
 Local-first. Incentive-aligned. Verifiable.
@@ -386,7 +386,7 @@ Example (see full schema in `openclaw.plugin.json`):
               "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 }
             },
             "ledger": { "faucetEnabled": false, "initialCreditsPerAgent": 0, "balancesMode": "initial", "balances": {} }

package/openclaw.plugin.json

@@ -61,8 +61,8 @@
                 "properties": {
                   "type": {
                     "type": "string",
-                    "enum": ["SINGLE_WINNER", "MAJORITY_VOTE", "WEIGHTED_REPUTATION", "TRUSTED_ARBITER"],
-                    "default": "SINGLE_WINNER"
+                    "enum": ["FIRST_SUBMISSION_WINS", "APPROVAL_VOTE", "MAJORITY_VOTE", "WEIGHTED_REPUTATION", "TRUSTED_ARBITER"],
+                    "default": "FIRST_SUBMISSION_WINS"
                   },
                   "trustedArbiterAgentId": { "type": "string", "default": "" }
                 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consensus-tools/consensus-tools",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "main": "index.ts",
   "bin": {
@@ -18,6 +18,7 @@
     "bin",
     "index.ts",
     "src",
+    "assets",
     "openclaw.plugin.json",
     "README.md"
   ],

package/src/cli.ts

@@ -237,16 +237,23 @@ function registerConsensusSubcommands(
     .description('Cast a vote')
     .option('--submission <id>', 'Submission id to vote for')
     .option('--choice <key>', 'Choice key to vote for')
+    .option('--yes', 'Approval vote: yes (+1)')
+    .option('--no', 'Approval vote: no (-1)')
     .option('--weight <n>', 'Vote weight', parseFloat)
+    .option('--stake <n>', 'Stake amount locked for this vote (staked settlement)', parseFloat)
     .option('--json', 'JSON output')
     .action(async (jobId: string, opts: any) => {
+      const hasYesNo = Boolean(opts.yes || opts.no);
+      const score = hasYesNo ? (opts.no ? -1 : 1) : (opts.weight ?? 1);
+
       const vote = await backend.vote(agentId, jobId, {
         submissionId: opts.submission,
         choiceKey: opts.choice,
         targetType: opts.submission ? 'SUBMISSION' : opts.choice ? 'CHOICE' : undefined,
         targetId: opts.submission ?? opts.choice,
-        weight: opts.weight ?? 1,
-        score: opts.weight ?? 1
+        weight: opts.weight ?? (hasYesNo ? 1 : undefined),
+        score,
+        stakeAmount: opts.stake
       });
       output(vote, opts.json);
     });
@@ -582,6 +589,16 @@ function commonSh(): string {
     '  echo "$CONSENSUS_ROOT"',
     '}',
     '',
+    'local_state_file() {',
+    '  # Engine-parity local state file (JsonStorage)',
+    '  if [[ -n "${CONSENSUS_STATE_FILE:-}" ]]; then',
+    '    echo "${CONSENSUS_STATE_FILE}"',
+    '  else',
+    '    echo "$(local_root)/state.json"',
+    '  fi',
+    '}',
+    '',
+    '',
     'ensure_local_board() {',
     '  local root; root="$(local_root)"',
     '  mkdir -p "$root/jobs"',
@@ -683,39 +700,35 @@ function jobsPostSh(): string {
     '',
     'POLICY="${CONSENSUS_DEFAULT_POLICY:-HIGHEST_CONFIDENCE_SINGLE}"',
     'REWARD="${CONSENSUS_DEFAULT_REWARD:-8}"',
-    'STAKE="${CONSENSUS_DEFAULT_STAKE:-4}"',
-    'LEASE_SECONDS="${CONSENSUS_DEFAULT_LEASE_SECONDS:-180}"',
+    'STAKE_REQUIRED="${CONSENSUS_DEFAULT_STAKE:-4}"',
+    'EXPIRES_SECONDS="${CONSENSUS_DEFAULT_EXPIRES_SECONDS:-86400}"',
     'MODE="$(mode)"',
     '',
     'if [[ "$MODE" == "local" ]]; then',
     '  ensure_local_board',
-    '  local id; id="$(rand_id "job")"',
-    '',
-    '  local title_json desc_json input_json',
-    '  title_json="$(json_escape "$TITLE")"',
-    '  desc_json="$(json_escape "${DESC:-}")"',
-    '  input_json="$(json_escape "${INPUT:-}")"',
-    '',
-    '  local job_json',
-    '  job_json="$(cat <<JSON',
-    '{',
-    '  "id": "$id",',
-    '  "title": $title_json,',
-    '  "desc": $desc_json,',
-    '  "input": $input_json,',
-    '  "mode": "SUBMISSION",',
-    '  "policyKey": "$POLICY",',
-    '  "rewardAmount": $REWARD,',
-    '  "stakeAmount": $STAKE,',
-    '  "leaseSeconds": $LEASE_SECONDS,',
-    '  "status": "OPEN",',
-    '  "createdAt": "$(now_iso)"',
-    '}',
-    'JSON',
-    ')"',
-    '  write_json_file "$(job_file "$id")" "$job_json"',
-    '  ensure_job_dir "$id"',
-    '  echo "$job_json"',
+    '  state_file="$(local_state_file)"',
+    '  node --import tsx --input-type=module - "$state_file" "$TITLE" "$DESC" "$INPUT" "$POLICY" "$REWARD" "$STAKE_REQUIRED" "$EXPIRES_SECONDS" <<\'NODE\'',
+    "import { JsonStorage } from '@consensus-tools/consensus-tools/src/storage/JsonStorage.ts';",
+    "import { LedgerEngine } from '@consensus-tools/consensus-tools/src/ledger/ledger.ts';",
+    "import { JobEngine } from '@consensus-tools/consensus-tools/src/jobs/engine.ts';",
+    "import { defaultConfig } from '@consensus-tools/consensus-tools/src/config.ts';",
+    'const [stateFile,title,desc,input,policy,reward,stake,expires]=process.argv.slice(2);',
+    'const storage=new JsonStorage(stateFile); await storage.init();',
+    'const ledger=new LedgerEngine(storage, defaultConfig);',
+    'const engine=new JobEngine(storage, ledger, defaultConfig);',
+    "const job = await engine.postJob('cli@local', {",
+    '  title,',
+    '  desc,',
+    '  inputRef: input,',
+    '  policyKey: policy,',
+    '  rewardAmount: Number(reward),',
+    '  reward: Number(reward),',
+    '  stakeRequired: Number(stake),',
+    '  stakeAmount: Number(stake),',
+    '  expiresSeconds: Number(expires)',
+    '});',
+    'console.log(JSON.stringify(job, null, 2));',
+    'NODE',
     '  exit 0',
     'fi',
     '',
@@ -729,14 +742,13 @@ function jobsPostSh(): string {
     '  "mode": "SUBMISSION",',
     '  "policyKey": "$POLICY",',
     '  "rewardAmount": $REWARD,',
-    '  "stakeAmount": $STAKE,',
-    '  "leaseSeconds": $LEASE_SECONDS',
+    '  "stakeAmount": $STAKE_REQUIRED,',
+    '  "leaseSeconds": ${CONSENSUS_DEFAULT_LEASE_SECONDS:-180}',
     '}',
     'JSON',
     ')"',
     'curl_json "POST" "$base/jobs" "$payload"',
     'echo',
-    ''
   ].join('\n');
 }
 
@@ -756,14 +768,26 @@ function jobsGetSh(): string {
     '',
     'if [[ "$MODE" == "local" ]]; then',
     '  ensure_local_board',
-    '  read_json_file "$(job_file "$JOB_ID")"',
+    '  state_file="$(local_state_file)"',
+    '  node --import tsx --input-type=module - "$state_file" "$JOB_ID" <<\'NODE\'',
+    "import { JsonStorage } from '@consensus-tools/consensus-tools/src/storage/JsonStorage.ts';",
+    "import { LedgerEngine } from '@consensus-tools/consensus-tools/src/ledger/ledger.ts';",
+    "import { JobEngine } from '@consensus-tools/consensus-tools/src/jobs/engine.ts';",
+    "import { defaultConfig } from '@consensus-tools/consensus-tools/src/config.ts';",
+    'const [stateFile, jobId] = process.argv.slice(2);',
+    'const storage=new JsonStorage(stateFile); await storage.init();',
+    'const ledger=new LedgerEngine(storage, defaultConfig);',
+    'const engine=new JobEngine(storage, ledger, defaultConfig);',
+    'const job = await engine.getJob(jobId);',
+    "if (!job) { console.error('Job not found'); process.exit(1); }",
+    'console.log(JSON.stringify(job, null, 2));',
+    'NODE',
     '  exit 0',
     'fi',
     '',
     'base="$(remote_base)"',
     'curl -sS "$base/jobs/$JOB_ID" -H "$(remote_auth_header)"',
     'echo',
-    ''
   ].join('\n');
 }
 
@@ -777,13 +801,23 @@ function jobsListSh(): string {
     '',
     'if [[ "$MODE" == "local" ]]; then',
     '  ensure_local_board',
-    '  root="$(local_root)"',
-    '  ls -1 "$root/jobs"/*.json 2>/dev/null | sed "s#.*/##" | sed "s#\\.json$##" || true',
+    '  state_file="$(local_state_file)"',
+    '  node --import tsx --input-type=module - "$state_file" <<\'NODE\'',
+    "import { JsonStorage } from '@consensus-tools/consensus-tools/src/storage/JsonStorage.ts';",
+    "import { LedgerEngine } from '@consensus-tools/consensus-tools/src/ledger/ledger.ts';",
+    "import { JobEngine } from '@consensus-tools/consensus-tools/src/jobs/engine.ts';",
+    "import { defaultConfig } from '@consensus-tools/consensus-tools/src/config.ts';",
+    'const [stateFile]=process.argv.slice(2);',
+    'const storage=new JsonStorage(stateFile); await storage.init();',
+    'const ledger=new LedgerEngine(storage, defaultConfig);',
+    'const engine=new JobEngine(storage, ledger, defaultConfig);',
+    'const jobs = await engine.listJobs({});',
+    'for (const j of jobs) console.log(j.id);',
+    'NODE',
     '  exit 0',
     'fi',
     '',
     'base="$(remote_base)"',
-    '# Optional: pass query string as $1, e.g. "status=OPEN&mode=SUBMISSION"',
     'QS="${1:-}"',
     'url="$base/jobs"',
     'if [[ -n "$QS" ]]; then',
@@ -791,7 +825,6 @@ function jobsListSh(): string {
     'fi',
     'curl -sS "$url" -H "$(remote_auth_header)"',
     'echo',
-    ''
   ].join('\n');
 }
 
@@ -804,10 +837,10 @@ function submissionsCreateSh(): string {
     'JOB_ID="${1:-}"',
     'ARTIFACT_JSON="${2:-}"',
     'SUMMARY="${3:-}"',
+    'CONFIDENCE="${4:-0.5}"',
     '',
     'if [[ -z "$JOB_ID" || -z "$ARTIFACT_JSON" ]]; then',
-    '  echo "Usage: submissions_create.sh <jobId> <artifact_json> [summary]" >&2',
-    '  echo "Example: submissions_create.sh job_... {\\\"toxic\\\":false,\\\"confidence\\\":0.98,\\\"brief_reason\\\":\\\"...\\\"}" >&2',
+    '  echo "Usage: submissions_create.sh <jobId> <artifact_json> [summary] [confidence]" >&2',
     '  exit 2',
     'fi',
     '',
@@ -815,23 +848,20 @@ function submissionsCreateSh(): string {
     '',
     'if [[ "$MODE" == "local" ]]; then',
     '  ensure_local_board',
-    '  ensure_job_dir "$JOB_ID"',
-    '',
-    '  sid="$(rand_id "sub")"',
-    '  summary_json="$(json_escape "${SUMMARY:-}")"',
-    '  sub_json="$(cat <<JSON',
-    '{',
-    '  "id": "$sid",',
-    '  "jobId": "$JOB_ID",',
-    '  "artifact": $ARTIFACT_JSON,',
-    '  "summary": $summary_json,',
-    '  "createdAt": "$(now_iso)",',
-    '  "status": "VALID"',
-    '}',
-    'JSON',
-    ')"',
-    '  write_json_file "$(job_dir "$JOB_ID")/submissions/${sid}.json" "$sub_json"',
-    '  echo "$sub_json"',
+    '  state_file="$(local_state_file)"',
+    '  node --import tsx --input-type=module - "$state_file" "$JOB_ID" "$ARTIFACT_JSON" "${SUMMARY:-}" "$CONFIDENCE" <<\'NODE\'',
+    "import { JsonStorage } from '@consensus-tools/consensus-tools/src/storage/JsonStorage.ts';",
+    "import { LedgerEngine } from '@consensus-tools/consensus-tools/src/ledger/ledger.ts';",
+    "import { JobEngine } from '@consensus-tools/consensus-tools/src/jobs/engine.ts';",
+    "import { defaultConfig } from '@consensus-tools/consensus-tools/src/config.ts';",
+    'const [stateFile, jobId, artifactJson, summary, conf] = process.argv.slice(2);',
+    'const artifacts = JSON.parse(artifactJson);',
+    'const storage=new JsonStorage(stateFile); await storage.init();',
+    'const ledger=new LedgerEngine(storage, defaultConfig);',
+    'const engine=new JobEngine(storage, ledger, defaultConfig);',
+    "const sub = await engine.submitJob('cli@local', jobId, { summary: summary || '', artifacts, confidence: Number(conf) });",
+    'console.log(JSON.stringify(sub, null, 2));',
+    'NODE',
     '  exit 0',
     'fi',
     '',
@@ -845,7 +875,6 @@ function submissionsCreateSh(): string {
     ')"',
     'curl_json "POST" "$base/jobs/$JOB_ID/submissions" "$payload"',
     'echo',
-    ''
   ].join('\n');
 }
 
@@ -865,15 +894,25 @@ function submissionsListSh(): string {
     '',
     'if [[ "$MODE" == "local" ]]; then',
     '  ensure_local_board',
-    '  ensure_job_dir "$JOB_ID"',
-    '  ls -1 "$(job_dir "$JOB_ID")/submissions"/*.json 2>/dev/null | xargs -I{} cat "{}" || true',
+    '  state_file="$(local_state_file)"',
+    '  node --import tsx --input-type=module - "$state_file" "$JOB_ID" <<\'NODE\'',
+    "import { JsonStorage } from '@consensus-tools/consensus-tools/src/storage/JsonStorage.ts';",
+    "import { LedgerEngine } from '@consensus-tools/consensus-tools/src/ledger/ledger.ts';",
+    "import { JobEngine } from '@consensus-tools/consensus-tools/src/jobs/engine.ts';",
+    "import { defaultConfig } from '@consensus-tools/consensus-tools/src/config.ts';",
+    'const [stateFile, jobId] = process.argv.slice(2);',
+    'const storage=new JsonStorage(stateFile); await storage.init();',
+    'const ledger=new LedgerEngine(storage, defaultConfig);',
+    'const engine=new JobEngine(storage, ledger, defaultConfig);',
+    'const list = await engine.listSubmissions(jobId);',
+    'for (const s of list) console.log(JSON.stringify(s, null, 2));',
+    'NODE',
     '  exit 0',
     'fi',
     '',
     'base="$(remote_base)"',
     'curl -sS "$base/jobs/$JOB_ID/submissions" -H "$(remote_auth_header)"',
     'echo',
-    ''
   ].join('\n');
 }
 
@@ -884,14 +923,27 @@ function votesCastSh(): string {
     'source "$(dirname "$0")/common.sh"',
     '',
     'JOB_ID="${1:-}"',
-    'TARGET_TYPE="${2:-}"   # SUBMISSION or CHOICE',
-    'TARGET_ID="${3:-}"     # submission id or choice key',
-    'WEIGHT="${4:-1}"',
+    'shift || true',
+    'TARGET_TYPE=""',
+    'TARGET_ID=""',
+    'WEIGHT="1"',
+    '',
+    'if [[ "${1:-}" == "SUBMISSION" || "${1:-}" == "CHOICE" ]]; then',
+    '  TARGET_TYPE="$1"; TARGET_ID="${2:-}"; WEIGHT="${3:-1}"',
+    'else',
+    '  while [[ $# -gt 0 ]]; do',
+    '    case "$1" in',
+    '      --submission) TARGET_TYPE="SUBMISSION"; TARGET_ID="${2:-}"; shift 2 ;;',
+    '      --choice)     TARGET_TYPE="CHOICE"; TARGET_ID="${2:-}"; shift 2 ;;',
+    '      --weight)     WEIGHT="${2:-1}"; shift 2 ;;',
+    '      *) echo "Unknown arg: $1" >&2; exit 2 ;;',
+    '    esac',
+    '  done',
+    'fi',
     '',
     'if [[ -z "$JOB_ID" || -z "$TARGET_TYPE" || -z "$TARGET_ID" ]]; then',
-    '  echo "Usage: votes_cast.sh <jobId> <targetType:SUBMISSION|CHOICE> <targetId> [weight]" >&2',
-    '  echo "Example: votes_cast.sh job_... SUBMISSION sub_... 1" >&2',
-    '  echo "Example: votes_cast.sh job_... CHOICE TOXIC_FALSE 1" >&2',
+    '  echo "Usage: votes_cast.sh <jobId> SUBMISSION <submissionId> [weight]" >&2',
+    '  echo "   or: votes_cast.sh <jobId> --submission <id> [--weight <n>]" >&2',
     '  exit 2',
     'fi',
     '',
@@ -899,22 +951,19 @@ function votesCastSh(): string {
     '',
     'if [[ "$MODE" == "local" ]]; then',
     '  ensure_local_board',
-    '  ensure_job_dir "$JOB_ID"',
-    '',
-    '  vid="$(rand_id "vote")"',
-    '  vote_json="$(cat <<JSON',
-    '{',
-    '  "id": "$vid",',
-    '  "jobId": "$JOB_ID",',
-    '  "targetType": "$TARGET_TYPE",',
-    '  "targetId": "$TARGET_ID",',
-    '  "weight": $WEIGHT,',
-    '  "createdAt": "$(now_iso)"',
-    '}',
-    'JSON',
-    ')"',
-    '  write_json_file "$(job_dir "$JOB_ID")/votes/${vid}.json" "$vote_json"',
-    '  echo "$vote_json"',
+    '  state_file="$(local_state_file)"',
+    '  node --import tsx --input-type=module - "$state_file" "$JOB_ID" "$TARGET_TYPE" "$TARGET_ID" "$WEIGHT" <<\'NODE\'',
+    "import { JsonStorage } from '@consensus-tools/consensus-tools/src/storage/JsonStorage.ts';",
+    "import { LedgerEngine } from '@consensus-tools/consensus-tools/src/ledger/ledger.ts';",
+    "import { JobEngine } from '@consensus-tools/consensus-tools/src/jobs/engine.ts';",
+    "import { defaultConfig } from '@consensus-tools/consensus-tools/src/config.ts';",
+    'const [stateFile, jobId, targetType, targetId, weight] = process.argv.slice(2);',
+    'const storage=new JsonStorage(stateFile); await storage.init();',
+    'const ledger=new LedgerEngine(storage, defaultConfig);',
+    'const engine=new JobEngine(storage, ledger, defaultConfig);',
+    "const vote = await engine.vote('cli@local', jobId, { targetType, targetId, submissionId: targetType==='SUBMISSION'?targetId:undefined, choiceKey: targetType==='CHOICE'?targetId:undefined, weight: Number(weight), score: Number(weight) });",
+    'console.log(JSON.stringify(vote, null, 2));',
+    'NODE',
     '  exit 0',
     'fi',
     '',
@@ -929,7 +978,6 @@ function votesCastSh(): string {
     ')"',
     'curl_json "POST" "$base/jobs/$JOB_ID/votes" "$payload"',
     'echo',
-    ''
   ].join('\n');
 }
 
@@ -949,15 +997,25 @@ function votesListSh(): string {
     '',
     'if [[ "$MODE" == "local" ]]; then',
     '  ensure_local_board',
-    '  ensure_job_dir "$JOB_ID"',
-    '  ls -1 "$(job_dir "$JOB_ID")/votes"/*.json 2>/dev/null | xargs -I{} cat "{}" || true',
+    '  state_file="$(local_state_file)"',
+    '  node --import tsx --input-type=module - "$state_file" "$JOB_ID" <<\'NODE\'',
+    "import { JsonStorage } from '@consensus-tools/consensus-tools/src/storage/JsonStorage.ts';",
+    "import { LedgerEngine } from '@consensus-tools/consensus-tools/src/ledger/ledger.ts';",
+    "import { JobEngine } from '@consensus-tools/consensus-tools/src/jobs/engine.ts';",
+    "import { defaultConfig } from '@consensus-tools/consensus-tools/src/config.ts';",
+    'const [stateFile, jobId] = process.argv.slice(2);',
+    'const storage=new JsonStorage(stateFile); await storage.init();',
+    'const ledger=new LedgerEngine(storage, defaultConfig);',
+    'const engine=new JobEngine(storage, ledger, defaultConfig);',
+    'const list = await engine.listVotes(jobId);',
+    'for (const v of list) console.log(JSON.stringify(v, null, 2));',
+    'NODE',
     '  exit 0',
     'fi',
     '',
     'base="$(remote_base)"',
     'curl -sS "$base/jobs/$JOB_ID/votes" -H "$(remote_auth_header)"',
     'echo',
-    ''
   ].join('\n');
 }
 
@@ -968,8 +1026,20 @@ function resolveSh(): string {
     'source "$(dirname "$0")/common.sh"',
     '',
     'JOB_ID="${1:-}"',
+    'shift || true',
+    'MANUAL_WINNER=""',
+    'MANUAL_SUB=""',
+    '',
+    'while [[ $# -gt 0 ]]; do',
+    '  case "$1" in',
+    '    --winner) MANUAL_WINNER="${2:-}"; shift 2 ;;',
+    '    --submission) MANUAL_SUB="${2:-}"; shift 2 ;;',
+    '    *) echo "Unknown arg: $1" >&2; exit 2 ;;',
+    '  esac',
+    'done',
+    '',
     'if [[ -z "$JOB_ID" ]]; then',
-    '  echo "Usage: resolve.sh <jobId>" >&2',
+    '  echo "Usage: resolve.sh <jobId> [--winner <agentId>] [--submission <submissionId>]" >&2',
     '  exit 2',
     'fi',
     '',
@@ -977,56 +1047,29 @@ function resolveSh(): string {
     '',
     'if [[ "$MODE" == "local" ]]; then',
     '  ensure_local_board',
-    '  ensure_job_dir "$JOB_ID"',
-    '',
-    '  # Local resolution policy: HIGHEST_CONFIDENCE_SINGLE for SUBMISSION jobs.',
-    '  # We pick the submission with max artifact.confidence if present.',
-    '  # If missing, we fall back to the most recent submission.',
-    '',
-    '  dir="$(job_dir "$JOB_ID")/submissions"',
-    '  if ! ls "$dir"/*.json >/dev/null 2>&1; then',
-    '    echo "No submissions found for $JOB_ID" >&2',
-    '    exit 1',
-    '  fi',
-    '',
-    '  python3 - <<\'PY\' "$JOB_ID" "$dir" | tee "$(job_dir "$JOB_ID")/result.json"',
-    'import json,glob,sys,os',
-    'job_id=sys.argv[1]; d=sys.argv[2]',
-    'subs=[]',
-    'for p in glob.glob(os.path.join(d,"*.json")):',
-    '    with open(p,"r") as f:',
-    '        s=json.load(f)',
-    '    conf=None',
-    '    try:',
-    '        conf=float(s.get("artifact",{}).get("confidence"))',
-    '    except Exception:',
-    '        conf=None',
-    '    subs.append((conf,s.get("createdAt",""),s,p))',
-    '# sort: confidence desc (None last), then createdAt desc',
-    'def key(t):',
-    '    conf,created,_,_ = t',
-    '    return (conf is not None, conf if conf is not None else -1.0, created)',
-    'subs_sorted=sorted(subs, key=key, reverse=True)',
-    'conf,created,s,p=subs_sorted[0]',
-    'result={',
-    '  "jobId": job_id,',
-    '  "mode": "SUBMISSION",',
-    '  "selectedSubmissionId": s.get("id"),',
-    '  "selectedSubmissionPath": p,',
-    '  "resolvedAt": __import__("datetime").datetime.utcnow().isoformat()+"Z",',
-    '  "artifact": s.get("artifact"),',
-    '  "summary": s.get("summary","")',
-    '}',
-    'print(json.dumps(result, indent=2))',
-    'PY',
-    '',
+    '  state_file="$(local_state_file)"',
+    '  node --import tsx --input-type=module - "$state_file" "$JOB_ID" "$MANUAL_WINNER" "$MANUAL_SUB" <<\'NODE\'',
+    "import { JsonStorage } from '@consensus-tools/consensus-tools/src/storage/JsonStorage.ts';",
+    "import { LedgerEngine } from '@consensus-tools/consensus-tools/src/ledger/ledger.ts';",
+    "import { JobEngine } from '@consensus-tools/consensus-tools/src/jobs/engine.ts';",
+    "import { defaultConfig } from '@consensus-tools/consensus-tools/src/config.ts';",
+    'const [stateFile, jobId, winner, subId] = process.argv.slice(2);',
+    'const storage=new JsonStorage(stateFile); await storage.init();',
+    'const ledger=new LedgerEngine(storage, defaultConfig);',
+    'const engine=new JobEngine(storage, ledger, defaultConfig);',
+    'const input:any = {};',
+    'if (winner) input.manualWinners = [winner];',
+    'if (subId) input.manualSubmissionId = subId;',
+    "const actor = winner || 'cli@local';",
+    'const res = await engine.resolveJob(actor, jobId, input);',
+    'console.log(JSON.stringify(res, null, 2));',
+    'NODE',
     '  exit 0',
     'fi',
     '',
     'base="$(remote_base)"',
     'curl -sS -X POST "$base/jobs/$JOB_ID/resolve" -H "$(remote_auth_header)"',
     'echo',
-    ''
   ].join('\n');
 }
 
@@ -1046,14 +1089,24 @@ function resultGetSh(): string {
     '',
     'if [[ "$MODE" == "local" ]]; then',
     '  ensure_local_board',
-    '  path="$(job_dir "$JOB_ID")/result.json"',
-    '  read_json_file "$path"',
+    '  state_file="$(local_state_file)"',
+    '  node --import tsx --input-type=module - "$state_file" "$JOB_ID" <<\'NODE\'',
+    "import { JsonStorage } from '@consensus-tools/consensus-tools/src/storage/JsonStorage.ts';",
+    "import { LedgerEngine } from '@consensus-tools/consensus-tools/src/ledger/ledger.ts';",
+    "import { JobEngine } from '@consensus-tools/consensus-tools/src/jobs/engine.ts';",
+    "import { defaultConfig } from '@consensus-tools/consensus-tools/src/config.ts';",
+    'const [stateFile, jobId] = process.argv.slice(2);',
+    'const storage=new JsonStorage(stateFile); await storage.init();',
+    'const ledger=new LedgerEngine(storage, defaultConfig);',
+    'const engine=new JobEngine(storage, ledger, defaultConfig);',
+    'const status = await engine.getStatus(jobId);',
+    'console.log(JSON.stringify(status.resolution ?? null, null, 2));',
+    'NODE',
     '  exit 0',
     'fi',
     '',
     'base="$(remote_base)"',
     'curl -sS "$base/jobs/$JOB_ID/result" -H "$(remote_auth_header)"',
     'echo',
-    ''
   ].join('\n');
 }

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

@@ -12,9 +12,10 @@ export type InitWizardResult = {
 
 const POLICY_CHOICES = [
   'HIGHEST_CONFIDENCE_SINGLE',
+  'APPROVAL_VOTE',
   'TOP_K_SPLIT',
   'OWNER_PICK',
-  'SINGLE_WINNER',
+  'FIRST_SUBMISSION_WINS',
   'MAJORITY_VOTE',
   'WEIGHTED_VOTE_SIMPLE',
   'WEIGHTED_REPUTATION',

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;

package/src/standalone.ts

@@ -163,7 +163,7 @@ function helpText() {
     '  jobs list [--tag <tag>] [--status <status>] [--mine] [--json]',
     '  submissions create <jobId> --artifact <json> [--summary <text>] [--confidence <n>] [--json]',
     '  submissions list <jobId> [--json]',
-    '  votes cast <jobId> [--submission <id> | --choice <key>] [--weight <n>] [--json]',
+    '  votes cast <jobId> [--submission <id> | --choice <key>] [--yes|--no] [--weight <n>] [--stake <n>] [--json]',
     '  votes list <jobId> [--json]',
     '  resolve <jobId> [--winner <agentId> ...] [--submission <submissionId>] [--json]',
     '  result get <jobId> [--json]',

package/src/testing/consensusTestRunner.ts

@@ -54,8 +54,9 @@ export type RunnerResult = {
 };
 
 const POLICY_TYPES: ConsensusPolicyType[] = [
-  'SINGLE_WINNER',
+  'FIRST_SUBMISSION_WINS',
   'HIGHEST_CONFIDENCE_SINGLE',
+  'APPROVAL_VOTE',
   'OWNER_PICK',
   'TOP_K_SPLIT',
   'MAJORITY_VOTE',
@@ -95,7 +96,13 @@ export async function runConsensusPolicyTests(options: RunnerOptions): Promise<R
         trustedArbiterAgentId: policy === 'TRUSTED_ARBITER' ? 'arbiter' : '',
         minConfidence: policy === 'HIGHEST_CONFIDENCE_SINGLE' ? 0.5 : undefined,
         topK: policy === 'TOP_K_SPLIT' ? 2 : undefined,
-        ordering: policy === 'TOP_K_SPLIT' ? 'confidence' : undefined
+        ordering: policy === 'TOP_K_SPLIT' ? 'confidence' : undefined,
+        // APPROVAL_VOTE defaults (pure approval): require at least 1 vote and accept any positive score
+        quorum: policy === 'APPROVAL_VOTE' ? 1 : undefined,
+        minScore: policy === 'APPROVAL_VOTE' ? 1 : undefined,
+        minMargin: policy === 'APPROVAL_VOTE' ? 0 : undefined,
+        tieBreak: policy === 'APPROVAL_VOTE' ? 'earliest' : undefined,
+        approvalVote: policy === 'APPROVAL_VOTE' ? { weightMode: 'equal', settlement: 'immediate' } : undefined
       },
       slashingPolicy: { enabled: false, slashPercent: 0, slashFlat: 0 }
     });
@@ -122,7 +129,7 @@ export async function runConsensusPolicyTests(options: RunnerOptions): Promise<R
     const correctSubmission = submissions.find((sub) => sub.artifacts?.answer === script.expectedAnswer) || submissions[0];
     log('[submission] selected correct', { submissionId: correctSubmission.id, agentId: correctSubmission.agentId });
 
-    if (policy === 'MAJORITY_VOTE' || policy === 'WEIGHTED_VOTE_SIMPLE' || policy === 'WEIGHTED_REPUTATION') {
+    if (policy === 'APPROVAL_VOTE' || policy === 'MAJORITY_VOTE' || policy === 'WEIGHTED_VOTE_SIMPLE' || policy === 'WEIGHTED_REPUTATION') {
       for (const persona of personas) {
         await engine.vote(persona.id, job.id, {
           submissionId: correctSubmission.id,

package/src/types.ts

@@ -1,6 +1,7 @@
 export type ConsensusPolicyType =
-  | 'SINGLE_WINNER'
+  | 'FIRST_SUBMISSION_WINS'
   | 'HIGHEST_CONFIDENCE_SINGLE'
+  | 'APPROVAL_VOTE'
   | 'OWNER_PICK'
   | 'TOP_K_SPLIT'
   | 'MAJORITY_VOTE'
@@ -24,10 +25,27 @@ export type VoteTargetType = 'SUBMISSION' | 'CHOICE';
 export interface ConsensusPolicyConfig {
   type: ConsensusPolicyType;
   trustedArbiterAgentId?: string;
+
+  // confidence-based policies
   minConfidence?: number;
+
+  // top-k policies
   topK?: number;
   ordering?: 'confidence' | 'score';
+
+  // vote-based policies
   quorum?: number;
+  minScore?: number;
+  minMargin?: number;
+  tieBreak?: 'earliest' | 'confidence' | 'arbiter';
+
+  // approval-vote specific
+  approvalVote?: {
+    weightMode?: 'equal' | 'explicit' | 'reputation';
+    settlement?: 'immediate' | 'staked' | 'oracle';
+    oracle?: 'trusted_arbiter';
+    voteSlashPercent?: number; // 0-1 (only for settlement=staked)
+  };
 }
 
 export interface SlashingPolicy {
@@ -162,7 +180,14 @@ export interface DiagnosticEntry {
   context?: Record<string, unknown>;
 }
 
-export type LedgerEntryType = 'FAUCET' | 'STAKE' | 'UNSTAKE' | 'PAYOUT' | 'SLASH' | 'ADJUST' | 'ESCROW_MINT';
+export type LedgerEntryType =
+  | 'FAUCET'
+  | 'STAKE'
+  | 'UNSTAKE'
+  | 'PAYOUT'
+  | 'SLASH'
+  | 'ADJUST'
+  | 'ESCROW_MINT';
 
 export interface LedgerEntry {
   id: string;