@thirdfy/agent-cli 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to `@thirdfy/agent-cli` are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Fixed
+
+- **Self preflight routing for swap-like actions:** `preflight --run-mode self` now selects the validation route by action capability. When an action advertises `supportsExecuteIntent=false` and `supportsBuildTx=true`, preflight uses `build-tx` directly instead of forcing execute-intent validation.
+
+## [0.1.8] - 2026-04-07
+
+**npm:** [`@thirdfy/agent-cli@0.1.8`](https://www.npmjs.com/package/@thirdfy/agent-cli/v/0.1.8)  
+**Git tag:** `v0.1.8`
+
+### Added
+
+- **Managed custodial lifecycle validation:** Added CLI E2E path for managed wallet delegation parity (`e2e:managed:delegation:parity`) and integrated coverage into production certification flow.
+
+### Changed
+
+- **Self execution diagnostics:** `doctor self` is now routed as an offline/local command and no longer depends on capabilities negotiation.
+- **Managed wallet command routing:** Removed thin wrapper indirection and wired `managed wallet init/grant` directly to delegation custodial handlers.
+
+### Fixed
+
+- **Effect check payload safety:** Hardened relaxed-mode effect-check fallback so warning payload shape remains deterministic in edge paths.
+- **Managed wallet integration test contract:** Validation-only detection now correctly uses `executionLane === 'validation_only'`, with explicit auth env isolation for deterministic header assertions.
+
+## [0.1.7] - 2026-04-05
+
+**npm:** [`@thirdfy/agent-cli@0.1.7`](https://www.npmjs.com/package/@thirdfy/agent-cli/v/0.1.7)  
+**Git tag:** [`v0.1.7`](https://github.com/thirdfy/agent-cli/releases/tag/v0.1.7)
+
+### Added
+
+- **Login and local config:** `thirdfy-agent login`, `logout` (including `logout --all` for local clear plus owner-session revoke when applicable), `whoami`, and `config set` / `config show` with defaults persisted under `~/.thirdfy/config.json`. Credential precedence remains: CLI flags, then environment variables, then saved config (see README).
+- **Custodial delegation (MetaMask-compatible path):** `delegation init-custodial` and `delegation custodial-grant` alongside the existing `delegation create` / `delegation activate` lifecycle.
+- **Delegation operator ergonomics:** `delegation show` as an alias for `delegation status`; expanded delegation inspection and parity-focused behavior for automation.
+- **E2E / certification:** Delegation parity and production certification scripts (`e2e:self:delegation:parity`, `e2e:delegation:prod:certify`) and related gates documented in internal runbooks.
+
+### Changed
+
+- **`delegation redeem`:** Respects the effective run mode (flag / env / profile) when building the execution path.
+- **Swap amount handling:** Clearer separation between *missing* and *ambiguous* amount-unit errors; stricter validation of human-form amounts (including excess precision) and decimals handling for `amountInHuman` flows.
+
+### Fixed
+
+- **Config and bootstrap:** Safer bootstrap output, tighter validation, preserved config semantics on upgrade paths, and `config set` rejects prototype-path keys to avoid confusing or unsafe key shapes.
+- **Login / token handling:** Stricter verification of token shape after login and safer config cloning for delegation-related routing.
+- **E2E:** Session-auth paths keep a dev-mock wallet fallback where intended so local and CI simulations stay stable.
+
+### Tooling
+
+- **Release workflow:** When a version is already published to npm, CI skips `npm publish` so tag-based runs can still create or align GitHub releases without duplicate-publish failures.
+
+---
+
+## [0.1.6] - 2026-03-30
+
+Prior release; see [git compare `v0.1.6...v0.1.7`](https://github.com/thirdfy/agent-cli/compare/v0.1.6...v0.1.7) for the full commit list.

package/README.md

@@ -33,6 +33,13 @@ Run without global install:
 npx @thirdfy/agent-cli --help
 ```
 
+## What's new in 0.1.8
+
+- Managed custodial lifecycle parity validation is now first-class in CLI E2E/certification.
+- `doctor self` runs as a local diagnostic command without capabilities negotiation.
+- Self-exec effect-check fallback payloads are hardened for deterministic automation parsing.
+- Managed wallet aliases (`managed wallet init/grant`) are wired directly to custodial delegation handlers.
+
 ## Quick start
 
 ```bash
@@ -101,6 +108,9 @@ thirdfy-agent agent register --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN
 - `run` auto-generates `idempotencyKey` by default when not provided.
 - For deterministic retries across workers/restarts, pass your own stable `--idempotency-key`.
 - `preflight` does not force idempotency keys.
+- `preflight --run-mode self` is capability-aware:
+  - if an action supports execute-intent validation, CLI uses `executionLane=validation_only` before building tx;
+  - if an action advertises `supportsExecuteIntent=false` and `supportsBuildTx=true`, CLI routes preflight directly to `build-tx`.
 
 ## Run modes and profiles
 
@@ -110,6 +120,12 @@ thirdfy-agent agent register --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN
 - `--run-mode self` -> self-custody rail (`build-tx` flow; default for `profile=personal`)
 - `--run-mode hybrid` -> self-custody + governance mirror metadata (default for `profile=builder`)
 
+| Goal | Recommended mode | Why |
+| --- | --- | --- |
+| BYOW signing and local custody | `self` | Keeps signing and broadcast on your wallet path. |
+| Managed delegated execution | `thirdfy` | Uses delegated governance rail for hosted execution. |
+| Self execution plus governance mirror checks | `hybrid` | Preserves local execution while emitting managed-lane mirrors. |
+
 Auth expectations by mode:
 
 - `self`: requires execution identity (`agentApiKey`) today; keyless self lane is blocked with deterministic `SELF_OPEN_DISABLED`.
@@ -133,6 +149,41 @@ thirdfy-agent whoami --json
 
 `profile use --profile <name>` resets run mode to that profile default unless `--run-mode` is explicitly provided.
 
+### One-command self execution (BYOW)
+
+Use `--broadcast` with `run --run-mode self` to keep one deterministic command for build/sign/send:
+
+```bash
+thirdfy-agent run \
+  --agent-api-key "$AGENT_API_KEY" \
+  --run-mode self \
+  --broadcast \
+  --action swap \
+  --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000","chainId":8453}' \
+  --json
+```
+
+The default `run --run-mode self` behavior is still unsigned-only (advanced users can sign externally).
+
+Self lane effect-check controls:
+
+```bash
+# strict: fail if no observable token delta
+thirdfy-agent self-exec ... --effect-check strict --json
+
+# relaxed (default): retry/read balances, warn on mismatch, do not false-fail the tx
+thirdfy-agent self-exec ... --effect-check relaxed --json
+
+# off: skip post-trade token-delta verification
+thirdfy-agent self-exec ... --effect-check off --json
+```
+
+Signer diagnostics:
+
+```bash
+thirdfy-agent doctor self --json
+```
+
 ## Swap amount contract (agent-safe)
 
 For `--action swap`, CLI enforces an explicit amount unit contract:
@@ -251,6 +302,16 @@ The CLI keeps compatibility with legacy `delegation create` + `delegation activa
 
 `delegation show` is a direct alias to `delegation status` for gator-style operator ergonomics.
 
+Managed easy-wallet command group:
+
+```bash
+thirdfy-agent managed wallet init --auth-token "$THIRDFY_AUTH_TOKEN" --json
+# or: --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN"
+thirdfy-agent managed wallet grant --auth-token "$THIRDFY_AUTH_TOKEN" --agent-key "0xYOUR_AGENT_KEY" --token-address "0x..." --max-usd-per-day 250 --json
+# or: --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN"
+thirdfy-agent managed run --agent-api-key "$AGENT_API_KEY" --run-mode thirdfy --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000"}' --json
+```
+
 ## More docs
 
 - OpenClaw CLI onboarding flow:
@@ -264,11 +325,16 @@ The CLI keeps compatibility with legacy `delegation create` + `delegation activa
 npm run validate:cli-contract-schemas
 npm test
 npm run smoke:cli
+npm run e2e:managed:delegation:parity
 ```
 
 ## Release
 
+Version history and user-facing notes: [CHANGELOG.md](./CHANGELOG.md) (for example [0.1.7](https://github.com/thirdfy/agent-cli/releases/tag/v0.1.7) — login/config UX, custodial delegation helpers, swap and config hardening).
+
 ```bash
 npm version patch
 npm publish --access public
 ```
+
+After publishing, push the matching tag (for example `v0.1.7`) so the [Release workflow](.github/workflows/release.yml) can create a GitHub release. If the package version is already on npm, the workflow skips republishing and still creates the release when triggered by a tag.

package/bin/thirdfy-agent.mjs

@@ -19,6 +19,7 @@ const DEFAULT_API_BASE = 'https://api.thirdfy.com';
 const DEFAULT_TIMEOUT_MS = 30000;
 const DEFAULT_CATALOG_CACHE_TTL_MS = 60_000;
 const RUN_MODES = ['thirdfy', 'self', 'hybrid'];
+const EFFECT_CHECK_MODES = ['strict', 'relaxed', 'off'];
 const PROFILE_DEFAULTS = {
   personal: 'self',
   builder: 'hybrid',
@@ -118,6 +119,9 @@ async function main() {
     case 'whoami':
       await commandProfileShow(context, subFlags);
       return;
+    case 'doctor self':
+      await commandDoctorSelf(context, subFlags);
+      return;
     default:
       break;
   }
@@ -125,6 +129,9 @@ async function main() {
   const capabilities = await negotiateCapabilities(context);
 
   switch (commandKey) {
+    case 'managed run':
+      await commandManagedRun(context, subFlags, capabilities);
+      return;
     case 'jeff trade':
       await commandRun(context, subFlags, capabilities);
       return;
@@ -201,6 +208,14 @@ async function main() {
     await commandAgentAuthVerify(context, subFlags, capabilities);
     return;
   }
+  if (commandKey3 === 'managed wallet init') {
+    await commandDelegationInitCustodial(context, subFlags, capabilities);
+    return;
+  }
+  if (commandKey3 === 'managed wallet grant') {
+    await commandDelegationCustodialGrant(context, subFlags, capabilities);
+    return;
+  }
 
   const rootCommand = parsed.positionals[0];
   switch (rootCommand) {
@@ -502,7 +517,7 @@ async function commandPreflight(ctx, flags, capabilities) {
   prepareActionParamsForFlags(flags, resolved.resolvedAction);
   const runMode = getEffectiveRunMode(ctx, flags);
   enforceChainCompatibility(capabilities, flags, runMode);
-  const backendResult = await runPreflightByMode(runMode, ctx, flags, resolved.resolvedAction);
+  const backendResult = await runPreflightByMode(runMode, ctx, flags, resolved);
   const normalized = backendResult.normalized;
   printEnvelope({
     success: normalized.success,
@@ -514,6 +529,7 @@ async function commandPreflight(ctx, flags, capabilities) {
       catalog: flags.catalog || null,
       requestedAction: resolved.requestedAction,
       resolvedAction: resolved.resolvedAction,
+      preflightRoute: backendResult.route,
       runMode,
       profile: ctx.profile || null,
       swapInput: flags.__swapInput || null,
@@ -533,6 +549,26 @@ async function commandRun(ctx, flags, capabilities) {
     skipPreflight,
   });
   const normalized = backendResult.normalized;
+  if (runMode === 'self' && parseBooleanFlag(flags.broadcast, false) && normalized?.success) {
+    const executed = await performSelfBroadcast(ctx, flags, resolved.resolvedAction, normalized);
+    printEnvelope({
+      success: true,
+      code: 'SELF_EXECUTED',
+      message: 'Self-custody execution completed',
+      data: executed,
+      meta: {
+        apiBase: ctx.apiBase,
+        requestedAction: resolved.requestedAction,
+        resolvedAction: resolved.resolvedAction,
+        runMode,
+        profile: ctx.profile || null,
+        skippedPreflight: skipPreflight,
+        swapInput: flags.__swapInput || null,
+        capabilitiesVersion: capabilities?.contractVersion || null,
+      },
+    });
+    return;
+  }
   printEnvelope({
     success: normalized.success,
     code: backendResult.code,
@@ -1194,108 +1230,124 @@ async function commandSelfExec(ctx, flags, capabilities) {
     process.exit(1);
   }
 
-  const txd = resolveUnsignedTx(selfResult);
-  if (!txd?.to || !txd?.data) {
-    printEnvelope({
-      success: false,
-      code: 'SELF_UNSIGNED_TX_MISSING',
-      message: 'Self execution did not return a valid unsigned transaction',
-      data: selfResult || {},
-      meta: {
-        apiBase: ctx.apiBase,
-        runMode: 'self',
-        resolvedAction: resolved.resolvedAction,
-      },
-    });
-    process.exit(1);
-  }
+  const executed = await performSelfBroadcast(ctx, flags, resolved.resolvedAction, selfResult);
 
-  const chainId = Number(txd.chainId || flags.chainId || 8453);
+  printEnvelope({
+    success: true,
+    code: 'SELF_EXECUTED',
+    message: 'Self-custody execution completed',
+    data: executed,
+    meta: {
+      apiBase: ctx.apiBase,
+      runMode: 'self',
+      resolvedAction: resolved.resolvedAction,
+      swapInput: flags.__swapInput || null,
+    },
+  });
+}
+
+async function commandDoctorSelf(ctx, flags) {
   const walletAddress = String(flags.walletAddress || process.env.MARKET_MAKER_WALLET_ADDRESS || '').trim();
   const owsWalletName = String(flags.owsWalletName || process.env.OWS_WALLET_NAME || '').trim();
-  const rpcUrl = String(flags.rpcUrl || process.env.BASE_RPC_URL || process.env.BASE_RPC_HTTP_URL || process.env.RPC_URL || 'https://mainnet.base.org').trim();
-  if (!walletAddress) {
-    throw createCliError('SIGNING_FAILED', 'Missing --wallet-address (or MARKET_MAKER_WALLET_ADDRESS) for self-exec signing.');
-  }
-  if (!owsWalletName) {
-    throw createCliError('SIGNING_FAILED', 'Missing --ows-wallet-name (or OWS_WALLET_NAME) for self-exec signing.');
-  }
-
-  const params = getPreparedParams(flags);
-  const effectTokenIn = String(flags.effectTokenIn || params.tokenIn || '').trim();
-  const effectTokenOut = String(flags.effectTokenOut || params.tokenOut || '').trim();
+  const rpcUrl = String(
+    flags.rpcUrl || process.env.BASE_RPC_URL || process.env.BASE_RPC_HTTP_URL || process.env.RPC_URL || 'https://mainnet.base.org'
+  ).trim();
+  const passphrasePresent = Boolean(String(process.env.OWS_PASSPHRASE || process.env.OWS_API_KEY || '').trim());
+  const checks = [];
 
-  let balancesBefore = null;
-  if (effectTokenIn && effectTokenOut) {
-    balancesBefore = await readEffectBalances(rpcUrl, walletAddress, effectTokenIn, effectTokenOut);
-  }
+  checks.push({
+    name: 'wallet-address',
+    ok: Boolean(walletAddress),
+    detail: walletAddress || 'missing --wallet-address / MARKET_MAKER_WALLET_ADDRESS',
+  });
+  checks.push({
+    name: 'ows-wallet-name',
+    ok: Boolean(owsWalletName),
+    detail: owsWalletName || 'missing --ows-wallet-name / OWS_WALLET_NAME',
+  });
+  checks.push({
+    name: 'ows-passphrase',
+    ok: passphrasePresent,
+    detail: passphrasePresent ? 'present' : 'missing OWS_PASSPHRASE (or OWS_API_KEY fallback)',
+  });
 
-  let submission;
   try {
-    submission = await signAndBroadcastWithOws({
-      txd,
-      chainId,
-      walletAddress,
-      owsWalletName,
-      rpcUrl,
-    });
+    resolveOwsBinary();
+    checks.push({ name: 'ows-binary', ok: true, detail: 'found' });
   } catch (error) {
-    throw createCliError('SIGNING_FAILED', error?.message || 'OWS signing failed');
+    checks.push({ name: 'ows-binary', ok: false, detail: error?.message || 'not found' });
   }
 
-  let receipt;
   try {
-    receipt = await submission.sent.wait();
+    await loadEthers();
+    checks.push({ name: 'ethers-runtime', ok: true, detail: 'loaded' });
   } catch (error) {
-    throw createCliError('BROADCAST_FAILED', error?.message || 'Broadcast wait failed');
-  }
-  const status = Number(receipt?.status ?? 0);
-  if (status !== 1) {
-    throw createCliError('BROADCAST_FAILED', 'Transaction receipt status is not success', {
-      receiptStatus: receipt?.status ?? null,
-      txHash: submission.sent.hash,
-    });
+    checks.push({ name: 'ethers-runtime', ok: false, detail: error?.message || 'missing ethers dependency' });
   }
 
-  let effectCheck = { checked: false, hasEffect: null, inDeltaRaw: null, outDeltaRaw: null };
-  if (balancesBefore) {
-    const balancesAfter = await readEffectBalances(rpcUrl, walletAddress, effectTokenIn, effectTokenOut);
-    const inDeltaRaw = (BigInt(balancesBefore.tokenIn) - BigInt(balancesAfter.tokenIn)).toString();
-    const outDeltaRaw = (BigInt(balancesAfter.tokenOut) - BigInt(balancesBefore.tokenOut)).toString();
-    const hasEffect = BigInt(inDeltaRaw) > 0n || BigInt(outDeltaRaw) > 0n;
-    effectCheck = {
-      checked: true,
-      hasEffect,
-      inDeltaRaw,
-      outDeltaRaw,
-    };
-    if (!hasEffect) {
-      throw createCliError('EFFECT_CHECK_FAILED', 'Transaction mined but did not produce observable token effect.', {
-        txHash: submission.sent.hash,
-        effectCheck,
-      });
-    }
+  try {
+    const ethers = await loadEthers();
+    const provider = new ethers.JsonRpcProvider(rpcUrl);
+    const block = await provider.getBlockNumber();
+    checks.push({ name: 'rpc-connectivity', ok: Number.isFinite(block), detail: `latestBlock=${block}` });
+  } catch (error) {
+    checks.push({ name: 'rpc-connectivity', ok: false, detail: error?.message || 'rpc check failed' });
   }
 
+  const ok = checks.every((entry) => entry.ok);
   printEnvelope({
-    success: true,
-    code: 'SELF_EXECUTED',
-    message: 'Self-custody execution completed',
+    success: ok,
+    code: ok ? 'DOCTOR_SELF_OK' : 'DOCTOR_SELF_FAILED',
+    message: ok ? 'Self lane signer diagnostics passed' : 'Self lane signer diagnostics found blocking issues',
     data: {
-      txHash: submission.sent.hash,
-      chainId,
-      blockNumber: receipt?.blockNumber ?? null,
-      status: receipt?.status ?? null,
-      unsignedTx: txd,
-      effectCheck,
+      checks,
+      hints: [
+        'For one-command self execution use: thirdfy-agent run --run-mode self --broadcast ...',
+        'Set --effect-check strict|relaxed|off to control post-trade effect validation behavior.',
+      ],
     },
     meta: {
       apiBase: ctx.apiBase,
       runMode: 'self',
+      rpcUrl,
+    },
+  });
+  if (!ok) process.exit(1);
+}
+
+async function commandManagedRun(ctx, flags, capabilities) {
+  const mode = normalizeManagedRunMode(flags.runMode || 'thirdfy');
+  const managedFlags = { ...flags, runMode: mode };
+  const resolved = await resolveActionSelection(ctx, managedFlags);
+  prepareActionParamsForFlags(managedFlags, resolved.resolvedAction);
+  enforceChainCompatibility(capabilities, managedFlags, mode);
+  const skipPreflight = Boolean(managedFlags.skipPreflight);
+  const backendResult = await runExecutionByMode(mode, ctx, managedFlags, resolved, {
+    skipPreflight,
+  });
+  const normalized = backendResult.normalized;
+  printEnvelope({
+    success: normalized.success,
+    code: normalized.success ? 'MANAGED_RUN_QUEUED' : backendResult.code,
+    message: normalized.success
+      ? mode === 'hybrid'
+        ? 'Managed easy-wallet hybrid execution prepared'
+        : 'Managed easy-wallet execution queued'
+      : backendResult.message,
+    data: normalized,
+    meta: {
+      apiBase: ctx.apiBase,
+      requestedAction: resolved.requestedAction,
       resolvedAction: resolved.resolvedAction,
-      swapInput: flags.__swapInput || null,
+      lane: 'managed_easy_wallet',
+      runMode: mode,
+      skippedPreflight: skipPreflight,
+      profile: ctx.profile || null,
+      swapInput: managedFlags.__swapInput || null,
+      capabilitiesVersion: capabilities?.contractVersion || null,
     },
   });
+  if (!normalized.success) process.exit(1);
 }
 
 async function commandProfileInit(ctx, flags) {
@@ -1543,6 +1595,14 @@ function normalizeRunMode(value) {
   throw new Error(`Unsupported --run-mode "${value}". Supported: ${RUN_MODES.join(', ')}`);
 }
 
+function normalizeManagedRunMode(value) {
+  const mode = normalizeRunMode(value || 'thirdfy');
+  if (mode === 'self') {
+    throw new Error('Managed lane does not support run-mode=self. Use thirdfy or hybrid.');
+  }
+  return mode;
+}
+
 function getProfileConfigPath() {
   return path.join(os.homedir(), '.thirdfy', 'config.json');
 }
@@ -1651,13 +1711,22 @@ function enforceChainCompatibility(capabilities, flags, runMode) {
   }
 }
 
-async function runPreflightByMode(runMode, ctx, flags, resolvedAction) {
+function shouldUseBuildTxPreflight(runMode, resolved) {
+  if (runMode !== 'self') return false;
+  const meta = resolved?.resolvedActionMeta || null;
+  if (!meta || typeof meta !== 'object') return false;
+  return meta.supportsExecuteIntent === false && meta.supportsBuildTx === true;
+}
+
+async function runPreflightByMode(runMode, ctx, flags, resolved) {
+  const resolvedAction = resolved.resolvedAction;
   if (runMode === 'self') {
+    const route = shouldUseBuildTxPreflight(runMode, resolved) ? 'build_tx' : 'execute_intent_validation';
     const normalized = await executeSelfRun(
       ctx,
       flags,
       { resolvedAction },
-      { skipPreflight: false }
+      { skipPreflight: route === 'build_tx' }
     );
     const blockedByGovernance = !normalized.success && Boolean(normalized.preflightBlocked);
     return {
@@ -1666,6 +1735,7 @@ async function runPreflightByMode(runMode, ctx, flags, resolvedAction) {
         : normalized.success
           ? 'Self preflight completed (unsigned transaction ready)'
           : 'Self preflight failed',
+      route,
       normalized,
     };
   }
@@ -1686,6 +1756,7 @@ async function runPreflightByMode(runMode, ctx, flags, resolvedAction) {
       : runMode === 'hybrid'
         ? 'Hybrid mirror preflight failed'
         : 'Preflight failed',
+    route: 'execute_intent_validation',
     normalized,
   };
 }
@@ -1947,18 +2018,19 @@ async function resolveActionSelection(ctx, flags) {
     .map((action) => ({
       key: getActionKey(action),
       aliases: getActionAliases(action),
+      action,
     }))
     .filter((entry) => entry.key);
 
   if (!keyed.length) {
-    return { requestedAction, resolvedAction: requestedAction };
+    return { requestedAction, resolvedAction: requestedAction, resolvedActionMeta: null };
   }
 
   // Prefer direct action id matches over alias matches.
   // This keeps UX simple for commands like `--action swap` when another action aliases to "swap".
   const exactKey = keyed.filter((entry) => entry.key.toLowerCase() === requestedLower);
   if (exactKey.length === 1) {
-    return { requestedAction, resolvedAction: exactKey[0].key };
+    return { requestedAction, resolvedAction: exactKey[0].key, resolvedActionMeta: exactKey[0].action || null };
   }
   if (exactKey.length > 1) {
     throw new Error(
@@ -1970,7 +2042,7 @@ async function resolveActionSelection(ctx, flags) {
 
   const exactAlias = keyed.filter((entry) => entry.aliases.some((a) => a.toLowerCase() === requestedLower));
   if (exactAlias.length === 1) {
-    return { requestedAction, resolvedAction: exactAlias[0].key };
+    return { requestedAction, resolvedAction: exactAlias[0].key, resolvedActionMeta: exactAlias[0].action || null };
   }
   if (exactAlias.length > 1) {
     throw new Error(
@@ -1986,7 +2058,7 @@ async function resolveActionSelection(ctx, flags) {
       entry.aliases.some((a) => a.toLowerCase().includes(requestedLower))
   );
   if (fuzzy.length === 1) {
-    return { requestedAction, resolvedAction: fuzzy[0].key };
+    return { requestedAction, resolvedAction: fuzzy[0].key, resolvedActionMeta: fuzzy[0].action || null };
   }
   if (fuzzy.length > 1) {
     throw new Error(
@@ -2048,6 +2120,171 @@ function resolveUnsignedTx(result) {
   return null;
 }
 
+function parseBooleanFlag(value, defaultValue = false) {
+  if (value === undefined || value === null) return defaultValue;
+  if (typeof value === 'boolean') return value;
+  const normalized = String(value).trim().toLowerCase();
+  if (!normalized) return defaultValue;
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) return true;
+  if (['0', 'false', 'no', 'off'].includes(normalized)) return false;
+  return defaultValue;
+}
+
+function normalizeEffectCheckMode(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  if (!normalized) return 'relaxed';
+  if (EFFECT_CHECK_MODES.includes(normalized)) return normalized;
+  throw createCliError(
+    'EFFECT_CHECK_MODE_INVALID',
+    `Unsupported --effect-check "${value}". Supported: ${EFFECT_CHECK_MODES.join(', ')}.`
+  );
+}
+
+async function sleepMs(ms) {
+  const delay = Number(ms || 0);
+  if (!Number.isFinite(delay) || delay <= 0) return;
+  await new Promise((resolve) => setTimeout(resolve, delay));
+}
+
+async function resolveEffectCheckResult({
+  mode,
+  rpcUrl,
+  walletAddress,
+  tokenIn,
+  tokenOut,
+  balancesBefore,
+  retries,
+  waitMs,
+}) {
+  const baseResult = {
+    checked: true,
+    mode,
+    hasEffect: false,
+    inDeltaRaw: '0',
+    outDeltaRaw: '0',
+    attempts: 0,
+    retries: Math.max(0, Number(retries || 0)),
+  };
+  if (mode === 'off') {
+    return { checked: false, mode, hasEffect: null, inDeltaRaw: null, outDeltaRaw: null, reason: 'disabled' };
+  }
+  if (!tokenIn || !tokenOut || !balancesBefore) {
+    return { checked: false, mode, hasEffect: null, inDeltaRaw: null, outDeltaRaw: null, reason: 'token_pair_missing' };
+  }
+  const maxAttempts = Math.max(1, Number(retries || 0) + 1);
+  let last = null;
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    const balancesAfter = await readEffectBalances(rpcUrl, walletAddress, tokenIn, tokenOut);
+    const inDeltaRaw = (BigInt(balancesBefore.tokenIn) - BigInt(balancesAfter.tokenIn)).toString();
+    const outDeltaRaw = (BigInt(balancesAfter.tokenOut) - BigInt(balancesBefore.tokenOut)).toString();
+    const hasEffect = BigInt(inDeltaRaw) > 0n || BigInt(outDeltaRaw) > 0n;
+    last = {
+      checked: true,
+      mode,
+      hasEffect,
+      inDeltaRaw,
+      outDeltaRaw,
+      attempts: attempt,
+      retries: maxAttempts - 1,
+    };
+    if (hasEffect) return last;
+    if (attempt < maxAttempts) await sleepMs(waitMs);
+  }
+  return {
+    ...(last || baseResult),
+    warning: 'No balance delta observed after retries; treating as non-fatal in relaxed mode.',
+  };
+}
+
+async function performSelfBroadcast(ctx, flags, resolvedAction, selfResult) {
+  const txd = resolveUnsignedTx(selfResult);
+  if (!txd?.to || !txd?.data) {
+    throw createCliError('SELF_UNSIGNED_TX_MISSING', 'Self execution did not return a valid unsigned transaction');
+  }
+  const chainId = Number(txd.chainId || flags.chainId || 8453);
+  const walletAddress = String(flags.walletAddress || process.env.MARKET_MAKER_WALLET_ADDRESS || '').trim();
+  const owsWalletName = String(flags.owsWalletName || process.env.OWS_WALLET_NAME || '').trim();
+  const rpcUrl = String(
+    flags.rpcUrl || process.env.BASE_RPC_URL || process.env.BASE_RPC_HTTP_URL || process.env.RPC_URL || 'https://mainnet.base.org'
+  ).trim();
+  if (!walletAddress) {
+    throw createCliError('SIGNING_FAILED', 'Missing --wallet-address (or MARKET_MAKER_WALLET_ADDRESS) for self-exec signing.');
+  }
+  if (!owsWalletName) {
+    throw createCliError('SIGNING_FAILED', 'Missing --ows-wallet-name (or OWS_WALLET_NAME) for self-exec signing.');
+  }
+
+  const params = getPreparedParams(flags);
+  const effectTokenIn = String(flags.effectTokenIn || params.tokenIn || '').trim();
+  const effectTokenOut = String(flags.effectTokenOut || params.tokenOut || '').trim();
+  const effectMode = normalizeEffectCheckMode(flags.effectCheck || process.env.THIRDFY_EFFECT_CHECK || 'relaxed');
+  const effectRetries = Number(flags.effectCheckRetries || process.env.THIRDFY_EFFECT_CHECK_RETRIES || 2);
+  const effectWaitMs = Number(flags.effectCheckWaitMs || process.env.THIRDFY_EFFECT_CHECK_WAIT_MS || 1200);
+
+  let balancesBefore = null;
+  if (effectMode !== 'off' && effectTokenIn && effectTokenOut) {
+    balancesBefore = await readEffectBalances(rpcUrl, walletAddress, effectTokenIn, effectTokenOut);
+  }
+
+  let submission;
+  try {
+    submission = await signAndBroadcastWithOws({
+      txd,
+      chainId,
+      walletAddress,
+      owsWalletName,
+      rpcUrl,
+    });
+  } catch (error) {
+    throw createCliError('SIGNING_FAILED', error?.message || 'OWS signing failed');
+  }
+
+  let receipt;
+  try {
+    receipt = await submission.sent.wait();
+  } catch (error) {
+    throw createCliError('BROADCAST_FAILED', error?.message || 'Broadcast wait failed');
+  }
+  const status = Number(receipt?.status ?? 0);
+  if (status !== 1) {
+    throw createCliError('BROADCAST_FAILED', 'Transaction receipt status is not success', {
+      receiptStatus: receipt?.status ?? null,
+      txHash: submission.sent.hash,
+    });
+  }
+
+  const effectCheck = await resolveEffectCheckResult({
+    mode: effectMode,
+    rpcUrl,
+    walletAddress,
+    tokenIn: effectTokenIn,
+    tokenOut: effectTokenOut,
+    balancesBefore,
+    retries: effectRetries,
+    waitMs: effectWaitMs,
+  });
+  if (effectCheck.checked && !effectCheck.hasEffect && effectMode === 'strict') {
+    throw createCliError('EFFECT_CHECK_FAILED', 'Transaction mined but did not produce observable token effect.', {
+      txHash: submission.sent.hash,
+      effectCheck,
+      mode: effectMode,
+    });
+  }
+
+  return {
+    txHash: submission.sent.hash,
+    chainId,
+    blockNumber: receipt?.blockNumber ?? null,
+    status: receipt?.status ?? null,
+    unsignedTx: txd,
+    effectCheck,
+    lane: 'self',
+    signer: 'ows',
+    resolvedAction,
+    apiBase: ctx.apiBase,
+  };
+}
+
 async function loadEthers() {
   const candidates = ['ethers', path.join(process.cwd(), 'node_modules', 'ethers')];
   for (const candidate of candidates) {
@@ -2242,8 +2479,8 @@ Core commands:
   thirdfy-agent catalogs list [--json]
   thirdfy-agent actions [--catalog <id>] [--provider <id>] [--agent-api-key <key>] [--chain-id <id>] [--run-mode <mode>] [--json]
   thirdfy-agent delegation create --auth-token <token> --agent-key <key> --owner-address <addr> --token-address <addr> --max-usd-per-day <usd> [--session-account-address <addr>] [--json]
-  thirdfy-agent delegation init-custodial --auth-token <token> [--chain-id <id>] [--json]
-  thirdfy-agent delegation custodial-grant --auth-token <token> --agent-key <key> --token-address <addr> --max-usd-per-day <usd> [--chain-id <id>] [--period-duration <sec>] [--expiry-seconds <sec>] [--json]
+  thirdfy-agent delegation init-custodial [--auth-token <token> | --owner-session-token <token>] [--chain-id <id>] [--json]
+  thirdfy-agent delegation custodial-grant [--auth-token <token> | --owner-session-token <token>] --agent-key <key> --token-address <addr> --max-usd-per-day <usd> [--chain-id <id>] [--period-duration <sec>] [--expiry-seconds <sec>] [--json]
   thirdfy-agent delegation activate --auth-token <token> --agent-key <key> --wallet-address <addr> --session-account-address <addr> --delegation-manager <addr> --delegation <json> --signature <hex> [--json]
   thirdfy-agent delegation status --auth-token <token> --agent-key <key> [--verify] [--json]
   thirdfy-agent delegation show --auth-token <token> --agent-key <key> [--verify] [--json]
@@ -2251,6 +2488,9 @@ Core commands:
   thirdfy-agent delegation balance --auth-token <token> --agent-key <key> [--chain-id <id>] [--json]
   thirdfy-agent delegation revoke --auth-token <token> --agent-key <key> [--reason <text>] [--chain-id <id>] [--json]
   thirdfy-agent delegation redeem --agent-api-key <key> --action <id> --params <json> [--run-mode thirdfy|hybrid] [--estimated-amount-usd <usd>] [--json]
+  thirdfy-agent managed wallet init [--auth-token <token> | --owner-session-token <token>] [--chain-id <id>] [--json]
+  thirdfy-agent managed wallet grant [--auth-token <token> | --owner-session-token <token>] --agent-key <key> --token-address <addr> --max-usd-per-day <usd> [--chain-id <id>] [--period-duration <sec>] [--expiry-seconds <sec>] [--json]
+  thirdfy-agent managed run --agent-api-key <key> --action <id> --params <json> [--run-mode thirdfy|hybrid] [--idempotency-key <key>] [--json]
   thirdfy-agent credentials upsert --auth-token <token> --venue <id> --api-key <key> --api-secret <secret> [--json]
   thirdfy-agent credentials status --auth-token <token> [--venue <id>] [--json]
   thirdfy-agent agent auth challenge --agent-key <key> [--wallet-address <addr>] [--chain-id <id>] [--json]
@@ -2260,8 +2500,9 @@ Core commands:
   thirdfy-agent agent key rotate [--agent-key <key>] [--auth-token <token> | --owner-session-token <token>] [--json]
   thirdfy-agent agent key revoke [--agent-key <key>] [--auth-token <token> | --owner-session-token <token>] [--json]
   thirdfy-agent preflight --agent-api-key <key> --action <id> --params <json> [--run-mode <mode>] [--json]
-  thirdfy-agent run --agent-api-key <key> --action <id> --params <json> [--run-mode <mode>] [--idempotency-key <key>] [--json]
-  thirdfy-agent self-exec --agent-api-key <key> --action <id> --params <json> --wallet-address <addr> --ows-wallet-name <name> [--rpc-url <url>] [--json]
+  thirdfy-agent run --agent-api-key <key> --action <id> --params <json> [--run-mode <mode>] [--broadcast] [--idempotency-key <key>] [--json]
+  thirdfy-agent self-exec --agent-api-key <key> --action <id> --params <json> --wallet-address <addr> --ows-wallet-name <name> [--rpc-url <url>] [--effect-check strict|relaxed|off] [--json]
+  thirdfy-agent doctor self [--wallet-address <addr>] [--ows-wallet-name <name>] [--rpc-url <url>] [--json]
   thirdfy-agent jeff preflight --agent-api-key <key> --action <id> --params <json> [--run-mode <mode>] [--json]
   thirdfy-agent jeff trade --agent-api-key <key> --action <id> --params <json> [--run-mode <mode>] [--json]
   thirdfy-agent jeff status --intent-id <id> [--json]
@@ -2276,6 +2517,8 @@ Global flags:
   --env <file>       load env vars from file
   --timeout <ms>     request timeout
   --params <json>    for swap: exactly one of {amountInRaw} or {amountInHuman + tokenInDecimals}
+  --broadcast        with run --run-mode self, sign and broadcast using OWS
+  --effect-check <mode>  self-exec check mode: strict | relaxed | off (default: relaxed)
   --owner-session-token <token>  owner session token (or THIRDFY_OWNER_SESSION_TOKEN)
   --json             stable machine-readable output
   --verbose          print adapter diagnostics

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdfy/agent-cli",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {
@@ -12,6 +12,7 @@
     "src/contracts/cli/schemas/",
     "scripts/validate-cli-contract-schemas.mjs",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
@@ -25,6 +26,7 @@
     "e2e:delegation:lifecycle": "node ./scripts/e2e/delegation-lifecycle.mjs",
     "e2e:delegation:commands": "node ./scripts/e2e/delegation-command-parity.mjs",
     "e2e:self:delegation:parity": "node ./scripts/e2e/self-delegation-parity.mjs",
+    "e2e:managed:delegation:parity": "node ./scripts/e2e/managed-custodial-lifecycle.mjs",
     "e2e:delegation:prod:certify": "node ./scripts/e2e/prod-delegation-certify.mjs",
     "e2e:report:last": "node ./scripts/e2e/report-last.mjs",
     "smoke:cli": "node ./bin/thirdfy-agent.mjs --help && node ./bin/thirdfy-agent.mjs --version --json",
@@ -48,5 +50,8 @@
   "bugs": {
     "url": "https://github.com/thirdfy/agent-cli/issues"
   },
-  "homepage": "https://github.com/thirdfy/agent-cli#readme"
+  "homepage": "https://github.com/thirdfy/agent-cli#readme",
+  "dependencies": {
+    "ethers": "^6.16.0"
+  }
 }