yaml-flow 5.4.2 → 6.0.0

package/examples/browser/boards/portfolio-tracker/portfolio-tracker.py

@@ -0,0 +1,365 @@
+#!/usr/bin/env python3
+"""portfolio-tracker.py — E2E orchestrator for the portfolio board demo.
+
+Black-box CLI client. All board and card-store operations are performed by
+shelling out to board-live-cards-cli and card-store-cli. No env vars. No
+fallbacks or defaults.
+"""
+
+import copy
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+import argparse
+
+
+_CLI_PARSER = argparse.ArgumentParser()
+_MODE_GROUP = _CLI_PARSER.add_mutually_exclusive_group()
+_MODE_GROUP.add_argument('--run-pycli', action='store_true', help='Use pycli for board/card operations (default)')
+_MODE_GROUP.add_argument('--run-nodecli', action='store_true', help='Use node cli for board/card operations')
+_CLI_ARGS = _CLI_PARSER.parse_args()
+RUN_PYCLI = not _CLI_ARGS.run_nodecli
+
+# ── Path resolution ────────────────────────────────────────────────────────────
+_HERE = os.path.dirname(os.path.abspath(__file__))
+_REPO_ROOT = os.path.normpath(os.path.join(_HERE, '..', '..', '..', '..'))
+
+NODE = shutil.which('node')
+if not NODE:
+    print('[ERROR] node not found on PATH', file=sys.stderr)
+    sys.exit(1)
+
+BOARD_CLI       = os.path.join(_REPO_ROOT, 'board-live-cards-cli.js')
+CARD_STORE_CLI  = os.path.join(_REPO_ROOT, 'card-store.js')
+FETCH_PRICES_PY = os.path.join(_HERE, 'portfolio-tracker-fetch-prices.py')
+
+PYTHON = shutil.which('python')
+if not PYTHON:
+    print('[ERROR] python not found on PATH (required for portfolio-tracker-fetch-prices.py)', file=sys.stderr)
+    sys.exit(1)
+
+PYTHON_RUNNER = sys.executable or PYTHON
+
+BOARD_PYCLI = os.path.join(_REPO_ROOT, 'pycli', 'main', 'board_live_cards_pycli.py')
+CARD_STORE_PYCLI = os.path.join(_REPO_ROOT, 'pycli', 'main', 'card_store_pycli.py')
+QUICKJS_BUNDLE = os.path.join(_REPO_ROOT, 'dist', 'pycli', 'quickjs-board-runtime.global.js')
+
+if RUN_PYCLI:
+    if not os.path.exists(BOARD_PYCLI):
+        print(f'[ERROR] pycli entry not found: {BOARD_PYCLI}', file=sys.stderr)
+        sys.exit(1)
+    if not os.path.exists(CARD_STORE_PYCLI):
+        print(f'[ERROR] pycli entry not found: {CARD_STORE_PYCLI}', file=sys.stderr)
+        sys.exit(1)
+    if not os.path.exists(QUICKJS_BUNDLE):
+        print(f'[ERROR] quickjs bundle not found: {QUICKJS_BUNDLE}', file=sys.stderr)
+        print('Run from yaml-flow root: npm run build:quickjs', file=sys.stderr)
+        sys.exit(1)
+
+if RUN_PYCLI:
+    ACTIVE_BOARD_BIN = [PYTHON_RUNNER, BOARD_PYCLI]
+    ACTIVE_CARD_STORE_BIN = [PYTHON_RUNNER, CARD_STORE_PYCLI]
+    ACTIVE_BOARD_SUFFIX = ['--bundle', QUICKJS_BUNDLE]
+else:
+    ACTIVE_BOARD_BIN = [NODE, BOARD_CLI]
+    ACTIVE_CARD_STORE_BIN = [NODE, CARD_STORE_CLI]
+    ACTIVE_BOARD_SUFFIX = []
+
+# ── Runtime directories (under os.tmpdir()/experiment/) ───────────────────────
+_TMP_BASE       = tempfile.mkdtemp(prefix='experiment-')
+CARDSTORE_DIR   = os.path.join(_TMP_BASE, 'cardstore')
+BOARDRUNTIME_DIR = os.path.join(_TMP_BASE, 'boardruntime')
+OUTPUTS_DIR     = os.path.join(_TMP_BASE, 'outputs')
+
+CARDSTORE_REF    = f'::fs-path::{CARDSTORE_DIR}'
+BOARDRUNTIME_REF = f'::fs-path::{BOARDRUNTIME_DIR}'
+OUTPUTS_REF      = f'::fs-path::{OUTPUTS_DIR}'
+
+# ── Inline card definitions ────────────────────────────────────────────────────
+CARD_PORTFOLIO_FORM = {
+    "id": "portfolio-form",
+    "meta": {"title": "Portfolio Holdings Form"},
+    "provides": [{"bindTo": "holdings", "ref": "card_data.holdings"}],
+    "card_data": {"holdings": []},
+    "view": {
+        "elements": [
+            {"kind": "table", "label": "Holdings",
+             "data": {"bind": "card_data.holdings", "columns": ["symbol", "qty"]}}
+        ]
+    }
+}
+
+CARD_PRICE_FETCH = {
+    "id": "price-fetch",
+    "meta": {"title": "Fetch Market Prices"},
+    "requires": ["holdings"],
+    "provides": [{"bindTo": "prices", "ref": "fetched_sources.prices"}],
+    "card_data": {},
+    "source_defs": [{
+        "kind": "mock-quotes",
+        "bindTo": "prices",
+        "outputFile": "prices.json",
+        "projections": {"tickers": "requires.holdings.symbol"}
+    }],
+    "view": {
+        "elements": [
+            {"kind": "table", "label": "Market Prices",
+             "data": {"bind": "fetched_sources.prices"}}
+        ]
+    }
+}
+
+CARD_HOLDINGS_TABLE = {
+    "id": "holdings-table",
+    "meta": {"title": "Holdings Table"},
+    "requires": ["holdings", "prices"],
+    "provides": [{"bindTo": "table", "ref": "computed_values.table"}],
+    "card_data": {},
+    "compute": [{
+        "bindTo": "table",
+        "expr": (
+            '{ "rows": $map(requires.holdings, function($h) { '
+            '{ "symbol": $h.symbol, "qty": $h.qty, '
+            '"price": $lookup(requires.prices, $h.symbol), '
+            '"value": $h.qty * $lookup(requires.prices, $h.symbol) } }) }'
+        )
+    }],
+    "view": {
+        "elements": [
+            {"kind": "table", "label": "Portfolio Positions",
+             "data": {"bind": "computed_values.table.rows",
+                      "columns": ["symbol", "qty", "price", "value"]}}
+        ]
+    }
+}
+
+CARD_PORTFOLIO_VALUE = {
+    "id": "portfolio-value",
+    "meta": {"title": "Portfolio Total Value"},
+    "requires": ["table"],
+    "provides": [{"bindTo": "totalValue", "ref": "computed_values.totalValue"}],
+    "card_data": {},
+    "compute": [
+        {"bindTo": "totalValue", "expr": "$sum(requires.table.rows.value)"}
+    ],
+    "view": {
+        "elements": [
+            {"kind": "metric", "label": "Total Portfolio Value",
+             "data": {"bind": "computed_values.totalValue"}}
+        ]
+    }
+}
+
+# ── Helpers ────────────────────────────────────────────────────────────────────
+def set_holdings(card_json: dict, holdings: dict) -> dict:
+    card = copy.deepcopy(card_json)
+    card["card_data"]["holdings"] = [
+        {"symbol": symbol, "qty": qty}
+        for symbol, qty in holdings.items()
+    ]
+    return card
+
+
+def run_board(*args):
+    subprocess.run([*ACTIVE_BOARD_BIN, *args, *ACTIVE_BOARD_SUFFIX], check=True, shell=False)
+
+
+def run_board_with_input(*args, input_json: str):
+    subprocess.run(
+        [*ACTIVE_BOARD_BIN, *args, *ACTIVE_BOARD_SUFFIX],
+        input=input_json, check=True, shell=False, text=True,
+    )
+
+
+def run_board_capture(*args) -> str:
+    result = subprocess.run(
+        [*ACTIVE_BOARD_BIN, *args, *ACTIVE_BOARD_SUFFIX],
+        check=True, shell=False, capture_output=True, text=True,
+    )
+    return result.stdout
+
+
+def run_card_store_set(card: dict):
+    subprocess.run(
+        [*ACTIVE_CARD_STORE_BIN, 'set', '--store-ref', CARDSTORE_REF],
+        input=json.dumps(card),
+        check=True,
+        shell=False,
+        text=True,
+    )
+
+
+def read_json(path: str):
+    with open(path, encoding='utf-8') as f:
+        return json.load(f)
+
+
+def wait_for_completed(label: str, timeout_s: float = 10.0, poll_s: float = 0.5):
+    required_names = {'portfolio-form', 'price-fetch', 'holdings-table', 'portfolio-value'}
+    deadline = time.monotonic() + timeout_s
+    while time.monotonic() < deadline:
+        raw = run_board_capture('status', '--base-ref', BOARDRUNTIME_REF)
+        data = json.loads(raw).get('data', {})
+        cards = data.get('cards', [])
+        completed = {c['name'] for c in cards if c.get('status') == 'completed'}
+        if required_names.issubset(completed):
+            print(f'[{label}] all cards completed.')
+            return
+        time.sleep(poll_s)
+    # timed out — print status and exit
+    raw = run_board_capture('status', '--base-ref', BOARDRUNTIME_REF)
+    print(f'[ERROR] {label}: timed out waiting for all cards to complete.', file=sys.stderr)
+    print(raw, file=sys.stderr)
+    sys.exit(1)
+
+
+# ── T0a — Create runtime directories ──────────────────────────────────────────
+print('\n=== T0a: Create runtime directories ===')
+for d in (CARDSTORE_DIR, BOARDRUNTIME_DIR, OUTPUTS_DIR):
+    os.makedirs(d)
+    print(f'  created: {d}')
+
+# ── T0b — Init board ───────────────────────────────────────────────────────────
+print('\n=== T0b: Init board ===')
+_task_executor_body = json.dumps({
+    'task-executor-ref': {
+        'meta': 'task-executor',
+        'howToRun': 'local-python',
+        'whatToRun': f'::fs-path::{FETCH_PRICES_PY}',
+    }
+})
+run_board_with_input(
+    'init',
+    '--base-ref', BOARDRUNTIME_REF,
+    '--card-store-ref', CARDSTORE_REF,
+    '--outputs-store-ref', OUTPUTS_REF,
+    input_json=_task_executor_body,
+)
+
+# ── T0c — Set all cards into card store ────────────────────────────────────────
+print('\n=== T0c: Set all cards into card store ===')
+run_card_store_set(set_holdings(CARD_PORTFOLIO_FORM, {"AAPL": 50, "MSFT": 30}))
+run_card_store_set(CARD_PRICE_FETCH)
+run_card_store_set(CARD_HOLDINGS_TABLE)
+run_card_store_set(CARD_PORTFOLIO_VALUE)
+
+# ── T0d — Upsert cards to board ────────────────────────────────────────────────
+print('\n=== T0d: Upsert cards to board ===')
+for _card_id in ('portfolio-form', 'price-fetch', 'holdings-table', 'portfolio-value'):
+    run_board('upsert-card', '--base-ref', BOARDRUNTIME_REF, '--card-id', _card_id)
+
+# ── T1 — Wait for all cards completed ──────────────────────────────────────────
+print('\n=== T1: Wait for all cards completed ===')
+wait_for_completed('T1')
+
+_prices_path = os.path.join(OUTPUTS_DIR, 'data-objects', 'prices.json')
+_prices_t1 = read_json(_prices_path)
+assert isinstance(_prices_t1, dict) and len(_prices_t1) > 0, \
+    'T1: prices.json is empty or not an object'
+assert set(_prices_t1.keys()) == {'AAPL', 'MSFT'}, \
+    f'T1: expected keys {{AAPL, MSFT}}, got {set(_prices_t1.keys())}'
+assert all(isinstance(v, (int, float)) for v in _prices_t1.values()), \
+    'T1: all price values must be numbers'
+print('[T1] assertion passed: prices.json has AAPL, MSFT with numeric values.')
+
+# ── T2a — Update holdings (GOOG added) ────────────────────────────────────────
+print('\n=== T2a: Update holdings (GOOG added) ===')
+run_card_store_set(set_holdings(CARD_PORTFOLIO_FORM, {"AAPL": 50, "MSFT": 30, "GOOG": 100}))
+
+# ── T2b — Upsert portfolio-form with --restart ─────────────────────────────────
+print('\n=== T2b: Upsert portfolio-form --restart ===')
+run_board('upsert-card', '--base-ref', BOARDRUNTIME_REF,
+          '--card-id', 'portfolio-form', '--restart')
+
+# ── T2c — Wait and assert ──────────────────────────────────────────────────────
+print('\n=== T2c: Wait for all cards completed ===')
+wait_for_completed('T2c')
+
+_prices_t2c = read_json(_prices_path)
+assert set(_prices_t2c.keys()) == {'AAPL', 'MSFT', 'GOOG'}, \
+    f'T2c: expected keys {{AAPL, MSFT, GOOG}}, got {set(_prices_t2c.keys())}'
+
+_ht_cv_path = os.path.join(OUTPUTS_DIR, 'cards', 'holdings-table', 'computed_values.json')
+_ht_cv_t2c = read_json(_ht_cv_path)
+assert len(_ht_cv_t2c['table']['rows']) == 3, \
+    f'T2c: expected 3 rows in holdings-table, got {len(_ht_cv_t2c["table"]["rows"])}'
+print('[T2c] assertions passed: 3 tickers in prices, 3 rows in holdings-table.')
+
+# ── T3 — Retrigger price-fetch, wait ──────────────────────────────────────────
+print('\n=== T3: Retrigger price-fetch ===')
+run_board('retrigger', '--base-ref', BOARDRUNTIME_REF, '--id', 'price-fetch')
+wait_for_completed('T3')
+
+_prices_t3 = read_json(_prices_path)
+assert set(_prices_t3.keys()) == {'AAPL', 'MSFT', 'GOOG'}, \
+    f'T3: expected 3 tickers, got {set(_prices_t3.keys())}'
+assert _prices_t3 != _prices_t2c, \
+    'T3: prices must differ from T2c values after retrigger (random regeneration)'
+print('[T3] assertions passed: 3 tickers, prices differ from T2c.')
+
+# ── T4 — Rapid 5× portfolio-form updates (queue stress test) ──────────────────
+print('\n=== T4: Rapid 5x portfolio-form updates ===')
+for _holdings in [
+    {"AAPL": 50, "MSFT": 30, "GOOG": 100, "AMZN": 40},              # V3
+    {"AAPL": 45, "MSFT": 30, "GOOG": 110, "AMZN": 40, "TSLA": 60},  # V4
+    {"AAPL": 45, "MSFT": 30, "GOOG": 110, "AMZN": 100},              # V4a
+    {"AAPL": 45, "MSFT": 30, "GOOG": 110, "AMZN": 140, "TSLA": 60}, # V4b
+    {"AAPL": 40, "MSFT": 35, "GOOG": 120, "TSLA": 70},               # V5
+]:
+    run_card_store_set(set_holdings(CARD_PORTFOLIO_FORM, _holdings))
+    run_board('upsert-card', '--base-ref', BOARDRUNTIME_REF,
+              '--card-id', 'portfolio-form', '--restart')
+
+wait_for_completed('T4')
+
+_prices_t4 = read_json(_prices_path)
+assert set(_prices_t4.keys()) == {'AAPL', 'MSFT', 'GOOG', 'TSLA'}, \
+    f'T4: expected keys {{AAPL, MSFT, GOOG, TSLA}}, got {set(_prices_t4.keys())}'
+assert 'AMZN' not in _prices_t4, \
+    'T4: AMZN must not be present (board must have settled on V5 holdings)'
+print('[T4] assertions passed: V5 tickers only, AMZN absent.')
+
+# ── T5 — Print final status and cross-check ────────────────────────────────────
+print('\n=== T5: Print final status and cross-check ===')
+
+# Step 1: Wait for all cards completed (stable state before any assertions)
+wait_for_completed('T5')
+
+# Step 2: Capture live CLI status
+_cli_raw = run_board_capture('status', '--base-ref', BOARDRUNTIME_REF)
+_cli_status = json.loads(_cli_raw)['data']
+
+# Step 3: Read status.json from outputs store
+_file_status = read_json(os.path.join(OUTPUTS_DIR, 'status.json'))
+
+# Step 4: Cross-check CLI vs file status
+assert json.dumps(_cli_status, sort_keys=True) == json.dumps(_file_status, sort_keys=True), \
+    'T5: CLI status does not match status.json snapshot'
+print('[T5] cross-check passed: CLI status matches status.json.')
+
+# Step 5: Print holdings-table computed values
+_ht_cv = read_json(_ht_cv_path)
+print('\nFinal portfolio positions table:')
+print(json.dumps(_ht_cv['table'], indent=2))
+
+# Step 6: Totals cross-verify: holdings × prices == totalValue
+V5_HOLDINGS = {"AAPL": 40, "MSFT": 35, "GOOG": 120, "TSLA": 70}
+_prices_final = read_json(_prices_path)
+_pv_cv = read_json(
+    os.path.join(OUTPUTS_DIR, 'cards', 'portfolio-value', 'computed_values.json')
+)
+_total_value = _pv_cv['totalValue']
+_expected = sum(qty * _prices_final[sym] for sym, qty in V5_HOLDINGS.items())
+assert round(_expected, 2) == round(_total_value, 2), \
+    f'T5: totals mismatch: expected={round(_expected, 2)}, got={round(_total_value, 2)}'
+print(f'[T5] totals assertion passed: expected={round(_expected, 2)}, totalValue={round(_total_value, 2)}')
+
+# Step 7: Print full CLI status
+print('\nFinal board status:')
+print(json.dumps(_cli_status, indent=2))
+
+print('\n=== portfolio-tracker completed successfully ===')

package/examples/cli/step-machine-cli/portfolio-tracker/--base-ref/.runtime-out

@@ -0,0 +1 @@
+--base-ref\runtime-out

package/examples/cli/step-machine-cli/portfolio-tracker/--base-ref/board-graph.json

@@ -0,0 +1,32 @@
+{
+  "graph": {
+    "version": 1,
+    "config": {
+      "settings": {
+        "completion": "manual",
+        "refreshStrategy": "data-changed"
+      },
+      "tasks": {}
+    },
+    "state": {
+      "status": "running",
+      "tasks": {},
+      "availableOutputs": [],
+      "stuckDetection": {
+        "is_stuck": false,
+        "stuck_description": null,
+        "outputs_unresolvable": [],
+        "tasks_blocked": []
+      },
+      "lastUpdated": "2026-05-02T15:18:33.305Z",
+      "executionId": "live-1777735113305",
+      "executionConfig": {
+        "executionMode": "eligibility-mode",
+        "conflictStrategy": "alphabetical",
+        "completionStrategy": "manual"
+      }
+    },
+    "snapshotAt": "2026-05-02T15:18:33.305Z"
+  },
+  "lastDrainedJournalId": ""
+}

package/examples/cli/step-machine-cli/portfolio-tracker/handlers/_board-cli.js

@@ -6,6 +6,7 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const repoRoot = path.resolve(__dirname, '..', '..', '..', '..', '..');
 const boardCliPath = path.join(repoRoot, 'board-live-cards-cli.js');
+const cardStoreCliPath = path.join(repoRoot, 'card-store.js');
 
 export function runBoardCli(args, options = {}) {
   const { capture = false, cwd = process.cwd() } = options;
@@ -16,7 +17,6 @@ export function runBoardCli(args, options = {}) {
     stdio: capture ? 'pipe' : 'pipe',
     env: {
       ...process.env,
-      BOARD_LIVE_CARDS_NO_SPAWN: process.env.BOARD_LIVE_CARDS_NO_SPAWN ?? '1',
       BOARD_DIR: process.env.BOARD_DIR ?? '',
     },
   });
@@ -34,6 +34,58 @@ export function runBoardCli(args, options = {}) {
   return capture ? (result.stdout ?? '') : '';
 }
 
+/** Spawn CLI with JSON piped to stdin. */
+export function runBoardCliWithInput(args, inputJson, options = {}) {
+  const { cwd = process.cwd() } = options;
+  const result = spawnSync(process.execPath, [boardCliPath, ...args], {
+    input: inputJson,
+    cwd,
+    encoding: 'utf-8',
+    windowsHide: true,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: {
+      ...process.env,
+      BOARD_DIR: process.env.BOARD_DIR ?? '',
+    },
+  });
+
+  if (result.error) {
+    throw new Error(`Failed to launch board-live-cards-cli: ${result.error.message}`);
+  }
+
+  if ((result.status ?? 1) !== 0) {
+    const stderr = (result.stderr ?? '').trim();
+    const stdout = (result.stdout ?? '').trim();
+    throw new Error(`board-live-cards-cli failed (${result.status}): ${stderr || stdout || 'no output'}`);
+  }
+
+  return result.stdout ?? '';
+}
+
+/** Spawn card-store-cli with JSON piped to stdin. */
+export function runCardStoreCliWithInput(args, inputJson, options = {}) {
+  const { cwd = process.cwd() } = options;
+  const result = spawnSync(process.execPath, [cardStoreCliPath, ...args], {
+    input: inputJson,
+    cwd,
+    encoding: 'utf-8',
+    windowsHide: true,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+  if (result.error) {
+    throw new Error(`Failed to launch card-store-cli: ${result.error.message}`);
+  }
+
+  if ((result.status ?? 1) !== 0) {
+    const stderr = (result.stderr ?? '').trim();
+    const stdout = (result.stdout ?? '').trim();
+    throw new Error(`card-store-cli failed (${result.status}): ${stderr || stdout || 'no output'}`);
+  }
+
+  return result.stdout ?? '';
+}
+
 export async function readStdinJson() {
   let raw = '';
   process.stdin.setEncoding('utf-8');

package/examples/cli/step-machine-cli/portfolio-tracker/handlers/add-cards-cli.js

@@ -1,24 +1,33 @@
 #!/usr/bin/env node
 
-import { readStdinJson, runBoardCli, writeFailure, writeResult } from './_board-cli.js';
+import { readStdinJson, runBoardCli, runCardStoreCliWithInput, writeFailure, writeResult } from './_board-cli.js';
 
 try {
   const input = await readStdinJson();
   const boardDir = String(input.BOARD_DIR ?? '').trim();
-  const cardsGlob = String(input.CARDS_GLOB ?? '').trim();
+  const cards = Array.isArray(input.CARDS) ? input.CARDS : [];
 
-  if (!boardDir || !cardsGlob) {
-    writeFailure('BOARD_DIR and CARDS_GLOB are required');
+  if (!boardDir || cards.length === 0) {
+    writeFailure('BOARD_DIR and CARDS (array) are required');
     process.exit(0);
   }
 
-  runBoardCli(['upsert-card', '--rg', boardDir, '--card-glob', cardsGlob]);
+  const baseRef = `::fs-path::${boardDir}`;
+
+  // Write all cards to the card store in one call
+  runCardStoreCliWithInput(
+    ['set', '--store-ref', baseRef],
+    JSON.stringify(cards),
+  );
+
+  // Upsert all cards at once
+  runBoardCli(['upsert-card', '--base-ref', baseRef, '--all']);
 
   writeResult({
     result: 'success',
     data: {
       board_dir: boardDir,
-      cards_glob: cardsGlob,
+      count: cards.length,
     },
   });
 } catch (error) {

package/examples/cli/step-machine-cli/portfolio-tracker/handlers/init-board-cli.js

@@ -11,7 +11,12 @@ try {
     process.exit(0);
   }
 
-  runBoardCli(['init', boardDir]);
+  runBoardCli([
+    'init',
+    '--base-ref', `::fs-path::${boardDir}`,
+    '--card-store-ref', `::fs-path::${boardDir}`,
+    '--outputs-store-ref', `::fs-path::${boardDir}`,
+  ]);
   writeResult({
     result: 'success',
     data: {

package/examples/cli/step-machine-cli/portfolio-tracker/handlers/poll-status-cli.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+
+import { readStdinJson, runBoardCli, writeFailure, writeResult } from './_board-cli.js';
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+try {
+  const input = await readStdinJson();
+  const boardDir = String(input.BOARD_DIR ?? '').trim();
+  const expectedCardCount = Number(input.EXPECTED_CARD_COUNT ?? 0);
+  const timeoutMs = Number(input.TIMEOUT_MS ?? 30000);
+  const pollMs = Number(input.POLL_MS ?? 500);
+
+  if (!boardDir || expectedCardCount <= 0) {
+    writeFailure('BOARD_DIR and EXPECTED_CARD_COUNT are required');
+    process.exit(0);
+  }
+
+  const started = Date.now();
+
+  while (Date.now() - started < timeoutMs) {
+    const statusJson = runBoardCli(['status', '--base-ref', `::fs-path::${boardDir}`], { capture: true });
+    let cards = [];
+    try {
+      cards = JSON.parse(statusJson)?.data?.cards ?? [];
+    } catch { /* ignore parse errors */ }
+
+    const completedCount = cards.filter(c => c.status === 'completed').length;
+
+    if (cards.length >= expectedCardCount && completedCount >= expectedCardCount) {
+      writeResult({
+        result: 'success',
+        data: {
+          completed: true,
+          card_count: cards.length,
+          completed_count: completedCount,
+        },
+      });
+      process.exit(0);
+    }
+
+    await sleep(pollMs);
+  }
+
+  writeResult({
+    result: 'timeout',
+    data: {
+      completed: false,
+      error: `timed out waiting for ${expectedCardCount} cards to complete`,
+    },
+  });
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  writeFailure(message);
+}

package/examples/cli/step-machine-cli/portfolio-tracker/handlers/retrigger-cli.js

@@ -12,7 +12,7 @@ try {
     process.exit(0);
   }
 
-  runBoardCli(['retrigger', '--rg', boardDir, '--task', task]);
+  runBoardCli(['retrigger', '--base-ref', `::fs-path::${boardDir}`, '--id', task]);
 
   writeResult({
     result: 'success',

package/examples/cli/step-machine-cli/portfolio-tracker/handlers/status-cli.js

@@ -11,7 +11,7 @@ try {
     process.exit(0);
   }
 
-  const status = runBoardCli(['status', '--rg', boardDir], { capture: true });
+  const status = runBoardCli(['status', '--base-ref', `::fs-path::${boardDir}`], { capture: true });
 
   writeResult({
     result: 'success',

package/examples/cli/step-machine-cli/portfolio-tracker/handlers/update-holdings-cli.js

@@ -2,7 +2,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { readStdinJson, runBoardCli, writeFailure, writeResult } from './_board-cli.js';
+import { readStdinJson, runBoardCli, runCardStoreCliWithInput, writeFailure, writeResult } from './_board-cli.js';
 
 try {
   const input = await readStdinJson();
@@ -22,7 +22,12 @@ try {
   card.card_data.holdings = holdings;
   fs.writeFileSync(cardPath, `${JSON.stringify(card, null, 2)}\n`, 'utf-8');
 
-  runBoardCli(['upsert-card', '--rg', boardDir, '--card', cardPath, '--restart']);
+  const baseRef = `::fs-path::${boardDir}`;
+  runCardStoreCliWithInput(
+    ['set', '--store-ref', baseRef],
+    JSON.stringify(card),
+  );
+  runBoardCli(['upsert-card', '--base-ref', baseRef, '--card-id', card.id, '--restart']);
 
   writeResult({
     result: 'success',

package/examples/cli/step-machine-cli/portfolio-tracker/handlers/wait-completed-cli.js

@@ -22,8 +22,12 @@ try {
   const started = Date.now();
 
   while (Date.now() - started < timeoutMs) {
-    const status = runBoardCli(['status', '--rg', boardDir], { capture: true });
-    const complete = tasks.every((task) => new RegExp(`\\bcompleted\\s+${task}\\b`).test(status));
+    const statusJson = runBoardCli(['status', '--base-ref', `::fs-path::${boardDir}`], { capture: true });
+    let cards = [];
+    try {
+      cards = JSON.parse(statusJson)?.data?.cards ?? [];
+    } catch { /* ignore parse errors */ }
+    const complete = tasks.every((task) => cards.some(c => c.name === task && c.status === 'completed'));
 
     if (complete) {
       writeResult({