@xmemo/skill 1.1.25

package/skill/scripts/commands/account.mjs

@@ -0,0 +1,194 @@
+import {
+  EXIT_CODE,
+  exitCodeForError,
+} from '../lib/core.mjs';
+
+import {
+  makeHttpRequest,
+  handleRestError,
+  safeJson,
+  sanitizeTerminalText,
+} from '../lib/api.mjs';
+
+export async function handleAccount(ctx) {
+  const { command, options, flags, token } = ctx;
+
+  if (command === 'overview') {
+    try {
+      const res = await makeHttpRequest(options.baseUrl, '/v1/skill/operations', 'POST', {
+        operation: 'overview',
+        arguments: {},
+      }, {
+        'Authorization': `Bearer ${token}`
+      }, options.timeoutMs);
+
+      const data = handleRestError(res, {
+        notFoundMessage: 'Account overview not found.',
+        context: 'Get overview request',
+        options,
+      });
+
+      const result = (data && typeof data.result === 'object' && data.result !== null) ? data.result : data;
+
+      if (options.json) {
+        console.log(safeJson({
+          ok: true,
+          ...(data?.operation ? { operation: data.operation } : {}),
+          ...result,
+          result,
+        }));
+        process.exit(EXIT_CODE.SUCCESS);
+      }
+
+      console.log('XMemo Account Overview:');
+      console.log(`- Memories: ${result.memories_total ?? 0} total (${result.memories_active ?? 0} active, ${result.memories_archived ?? 0} archived, ${result.memories_forgotten ?? 0} forgotten)`);
+      console.log(`- Active Agents: ${result.agents_active ?? 0}`);
+      console.log(`- Storage: ${result.storage_mb ?? 0} MB`);
+      console.log(`- Tokens (30d): ${result.tokens_30d ?? 0}`);
+      process.exit(EXIT_CODE.SUCCESS);
+    } catch (e) {
+      console.error('Get overview failed:', e.message);
+      process.exit(exitCodeForError(e));
+    }
+  }
+
+  if (command === 'activity') {
+    const args = {};
+    if (flags.limit !== undefined) {
+      const parsed = Number(flags.limit);
+      args.limit = Number.isInteger(parsed) ? parsed : flags.limit;
+    }
+
+    try {
+      const res = await makeHttpRequest(options.baseUrl, '/v1/skill/operations', 'POST', {
+        operation: 'activity',
+        arguments: args,
+      }, {
+        'Authorization': `Bearer ${token}`
+      }, options.timeoutMs);
+
+      const data = handleRestError(res, {
+        notFoundMessage: 'Account activity not found.',
+        context: 'Get activity request',
+        options,
+      });
+
+      const result = (data && typeof data.result === 'object' && data.result !== null) ? data.result : data;
+
+      if (options.json) {
+        console.log(safeJson({
+          ok: true,
+          ...(data?.operation ? { operation: data.operation } : {}),
+          ...result,
+          result,
+        }));
+        process.exit(EXIT_CODE.SUCCESS);
+      }
+
+      const activityList = Array.isArray(result.activity) ? result.activity : [];
+      if (activityList.length === 0) {
+        console.log('No recent activity found.');
+        process.exit(EXIT_CODE.SUCCESS);
+      }
+
+      const totalInfo = result.total !== undefined ? ` (total: ${result.total})` : '';
+      console.log(`XMemo Recent Activity (${activityList.length}${totalInfo}):`);
+      activityList.forEach((item, idx) => {
+        const ts = item.ts || '(unknown date)';
+        const type = item.type || 'unknown';
+        const summary = item.summary || '';
+        const ref = item.ref_id ? ` [ref: ${item.ref_id}]` : '';
+        console.log(`[${idx + 1}] ${sanitizeTerminalText(ts)} | ${type.toUpperCase()} | ${sanitizeTerminalText(summary)}${ref}`);
+      });
+      process.exit(EXIT_CODE.SUCCESS);
+    } catch (e) {
+      console.error('Get activity failed:', e.message);
+      process.exit(exitCodeForError(e));
+    }
+  }
+
+  if (command === 'stats') {
+    const scope = flags.scope;
+    const path = flags.path;
+    const bucket = flags.bucket;
+    const memoryType = flags['memory-type'] !== undefined ? flags['memory-type'] : flags.memory_type;
+    const status = flags.status;
+    const source = flags.source;
+    const since = flags.since;
+    const until = flags.until;
+    const groupBy = flags['group-by'] !== undefined ? flags['group-by'] : flags.group_by;
+    const topN = flags['top-n'] !== undefined ? flags['top-n'] : flags.top_n;
+    const teamId = flags['team-id'] !== undefined ? flags['team-id'] : flags.team_id;
+
+    const queryParams = [];
+    if (scope) queryParams.push(`scope=${encodeURIComponent(scope)}`);
+    if (path) queryParams.push(`path=${encodeURIComponent(path)}`);
+    if (bucket) queryParams.push(`bucket=${encodeURIComponent(bucket)}`);
+    if (memoryType) queryParams.push(`memory_type=${encodeURIComponent(memoryType)}`);
+    if (status) queryParams.push(`status=${encodeURIComponent(status)}`);
+    if (source) queryParams.push(`source=${encodeURIComponent(source)}`);
+    if (since) queryParams.push(`since=${encodeURIComponent(since)}`);
+    if (until) queryParams.push(`until=${encodeURIComponent(until)}`);
+    if (groupBy) queryParams.push(`group_by=${encodeURIComponent(groupBy)}`);
+    if (topN !== undefined) queryParams.push(`top_n=${encodeURIComponent(topN)}`);
+    if (teamId) queryParams.push(`team_id=${encodeURIComponent(teamId)}`);
+
+    let endpoint = '/v1/memories/stats';
+    if (queryParams.length > 0) {
+      endpoint += `?${queryParams.join('&')}`;
+    }
+
+    try {
+      const res = await makeHttpRequest(options.baseUrl, endpoint, 'GET', null, {
+        'Authorization': `Bearer ${token}`
+      }, options.timeoutMs);
+
+      const data = handleRestError(res, {
+        notFoundMessage: 'Memory stats not found.',
+        context: 'Get memory stats request',
+        options,
+      });
+
+      if (options.json) {
+        console.log(safeJson({
+          ok: true,
+          ...data,
+        }));
+        process.exit(EXIT_CODE.SUCCESS);
+      }
+
+      if ((data.total_count ?? 0) === 0 && (data.filtered_count ?? 0) === 0) {
+        console.log('No memory statistics available.');
+        process.exit(EXIT_CODE.SUCCESS);
+      }
+
+      console.log('XMemo Memory Statistics:');
+      console.log(`- Total Memories: ${data.total_count ?? 0} (filtered: ${data.filtered_count ?? 0}, scanned: ${data.scanned_count ?? 0})`);
+      if (data.latest_at) console.log(`- Latest Memory: ${data.latest_at}`);
+      if (data.oldest_at) console.log(`- Oldest Memory: ${data.oldest_at}`);
+      if (data.type_counts && Object.keys(data.type_counts).length > 0) {
+        const counts = Object.entries(data.type_counts).map(([k, v]) => `${k}: ${v}`).join(', ');
+        console.log(`- Types: ${counts}`);
+      }
+      if (data.status_counts && Object.keys(data.status_counts).length > 0) {
+        const counts = Object.entries(data.status_counts).map(([k, v]) => `${k}: ${v}`).join(', ');
+        console.log(`- Status: ${counts}`);
+      }
+      if (data.bucket_counts && Object.keys(data.bucket_counts).length > 0) {
+        const counts = Object.entries(data.bucket_counts).map(([k, v]) => `${k}: ${v}`).join(', ');
+        console.log(`- Buckets: ${counts}`);
+      }
+      if (Array.isArray(data.groups) && data.groups.length > 0) {
+        console.log(`- Groups (${data.groups.length}):`);
+        data.groups.forEach((g) => {
+          const dims = g.group_by ? Object.entries(g.group_by).map(([k, v]) => `${k}=${v}`).join(', ') : '';
+          console.log(`  * [${dims}]: ${g.count}`);
+        });
+      }
+      process.exit(EXIT_CODE.SUCCESS);
+    } catch (e) {
+      console.error('Get memory stats failed:', e.message);
+      process.exit(exitCodeForError(e));
+    }
+  }
+}

package/skill/scripts/commands/auth-login.mjs

@@ -0,0 +1,234 @@
+import fs from 'node:fs/promises';
+
+import {
+  credentialsPath, SCRIPT_COMMAND, EXIT_CODE,
+  exitCodeForHttpStatus, exitCodeForErrorCode, exitCodeForError,
+} from '../lib/core.mjs';
+
+import {
+  requirePlaintextStorageConsent, saveToken, getStoredToken,
+  getStoredCredential, getInstallationFingerprint,
+} from '../lib/auth-state.mjs';
+
+import {
+  makeHttpRequest, parseJsonResponse, extractRequestId, apiErrorMessage, safeJson,
+  extractExpiresInSeconds, formatRemainingValidity, sanitizeTerminalText,
+  formatDuration, fetchTemporaryLimits,
+} from '../lib/api.mjs';
+
+export async function handleAuthLogin(ctx) {
+  const { command, options, flags, skillVersion } = ctx;
+  if (!skillVersion) {
+    throw new Error('handleAuthLogin requires ctx.skillVersion to be provided');
+  }
+
+  // 1. LOGIN
+  if (command === 'login') {
+    try {
+      requirePlaintextStorageConsent(options, 'Device login');
+      const res = await makeHttpRequest(options.baseUrl, '/v1/auth/device/start', 'POST', {
+        client_id: 'xmemo-skill', surface: 'standalone_skill', token_type: 'skill_token',
+        client_version: skillVersion,
+        scopes: ['memory:read', 'memory:write', 'memory:restore', 'ledger:write', 'ledger:read', 'knowledge:read']
+      }, {}, options.timeoutMs);
+      const data = parseJsonResponse(res, 'Device login start');
+      if (res.statusCode !== 200) {
+        const reqId = extractRequestId(data);
+        const reqSuffix = reqId ? ` (request_id: ${reqId})` : '';
+        console.error(`Failed to start device login: ${apiErrorMessage(data, safeJson(data))}${reqSuffix}`);
+        process.exit(exitCodeForErrorCode(data?.error?.code) ?? exitCodeForHttpStatus(res.statusCode));
+      }
+      const verificationUrl = data.verification_uri_complete || data.verification_uri;
+      if (!data.device_code || !verificationUrl) {
+        console.error('Failed to start device login: the service response omitted the device code or verification URL.');
+        process.exit(EXIT_CODE.SERVER_ERROR);
+      }
+      const expiresInSeconds = extractExpiresInSeconds(data);
+      const expiresInMs = Math.max(1, expiresInSeconds * 1000);
+      const loginDeadline = Date.now() + expiresInMs;
+      const countdownText = formatRemainingValidity(expiresInSeconds);
+      console.log(`To verify this device, open the following URL in your browser:\n\n  ${sanitizeTerminalText(verificationUrl)}\n\nOr enter the code: ${sanitizeTerminalText(data.user_code)}\n\nWaiting for authorization... (valid for ${countdownText})`);
+
+      const deviceCode = data.device_code;
+      const intervalSeconds = Number(data.interval);
+      let pollInterval = Number.isFinite(intervalSeconds) && intervalSeconds > 0
+        ? Math.max(1, intervalSeconds * 1000)
+        : 5000;
+      
+      const poll = async () => {
+        if (Date.now() >= loginDeadline) {
+          console.error('Login failed: the device authorization code expired before approval.');
+          process.exit(EXIT_CODE.AUTH_ERROR);
+        }
+        try {
+          const pollRes = await makeHttpRequest(options.baseUrl, '/v1/auth/device/token', 'POST', {
+            device_code: deviceCode,
+            grant_type: 'urn:ietf:params:oauth:grant-type:device_code'
+          }, {}, options.timeoutMs);
+          const pollData = parseJsonResponse(pollRes, 'Device login polling');
+          if (pollData.error) {
+            if (pollData.error === 'authorization_pending') {
+              setTimeout(poll, Math.min(pollInterval, Math.max(1, loginDeadline - Date.now())));
+            } else if (pollData.error === 'slow_down') {
+              pollInterval += 5000;
+              setTimeout(poll, Math.min(pollInterval, Math.max(1, loginDeadline - Date.now())));
+            } else {
+              console.error(`Login failed: ${sanitizeTerminalText(pollData.error_description || pollData.error)}`);
+              process.exit(EXIT_CODE.AUTH_ERROR);
+            }
+          } else if (pollData.access_token) {
+            try {
+              await saveToken(pollData.access_token, { credential_type: 'formal' }, { allowPlaintext: options.allowPlaintext, warn: true });
+              console.log(`✅ Authorization successful. Token stored in the explicitly approved user credential file: ${credentialsPath}\nToken value was not printed. Project files were not modified.`);
+              process.exit(EXIT_CODE.SUCCESS);
+            } catch (err) {
+              console.error('Failed to save credentials file:', err.message);
+              process.exit(EXIT_CODE.USER_ERROR);
+            }
+          } else {
+            console.error('Login failed: the token endpoint returned neither an access token nor a recognized pending status.');
+            process.exit(EXIT_CODE.SERVER_ERROR);
+          }
+        } catch (e) {
+          if (Date.now() >= loginDeadline) {
+            console.error('Login failed: the device authorization window expired after repeated polling errors.');
+            process.exit(EXIT_CODE.AUTH_ERROR);
+          }
+          console.error('Login polling error:', e.message);
+          setTimeout(poll, Math.min(pollInterval, Math.max(1, loginDeadline - Date.now())));
+        }
+      };
+      setTimeout(poll, Math.min(pollInterval, expiresInMs));
+    } catch (e) {
+      console.error('Login error:', e.message);
+      process.exit(exitCodeForError(e));
+    }
+    return;
+  }
+
+  // 1b. LIMITED NO-ACCOUNT-START REGISTRATION (explicit fallback only)
+  if (command === 'register') {
+    const reason = flags.reason;
+    if (!['unattended', 'declined'].includes(reason)) {
+      console.error(`Temporary registration is a conditional fallback. Use "${SCRIPT_COMMAND} register --reason unattended --allow-plaintext" when no human can log in, or "--reason declined --allow-plaintext" after the human explicitly declines formal registration.`);
+      process.exit(EXIT_CODE.USER_ERROR);
+    }
+    try {
+      requirePlaintextStorageConsent(options, 'Temporary registration');
+    } catch (e) {
+      console.error(`Temporary registration refused: ${e.message}`);
+      process.exit(EXIT_CODE.USER_ERROR);
+    }
+    if (await getStoredToken()) {
+      console.error(`A credential is already configured. Formal login is the recommended path; use "${SCRIPT_COMMAND} login" to refresh it instead of creating temporary access.`);
+      process.exit(EXIT_CODE.USER_ERROR);
+    }
+    try {
+      const limits = await fetchTemporaryLimits(options.baseUrl, options.timeoutMs);
+      const installation_fingerprint = await getInstallationFingerprint();
+      const res = await makeHttpRequest(options.baseUrl, '/v1/agents/register', 'POST', {
+        entry_type: 'skill',
+        client_name: 'xmemo-skill',
+        client_version: skillVersion,
+        installation_fingerprint,
+        runtime: `node ${process.version}`,
+        skill_package_id: 'xmemo-memory',
+        metadata: { registration_reason: reason },
+      }, {}, options.timeoutMs);
+      const data = parseJsonResponse(res, 'Temporary registration');
+      if (res.statusCode < 200 || res.statusCode >= 300 || !data.temporary_token) {
+        const err = new Error(apiErrorMessage(data, safeJson(data)));
+        err.statusCode = res.statusCode;
+        throw err;
+      }
+      await saveToken(data.temporary_token, {
+        credential_type: 'temporary',
+        agent_id: data.agent_id,
+        bind_url: data.bind_url,
+        registration_reason: reason,
+      }, { allowPlaintext: options.allowPlaintext, warn: true });
+      if (options.json) {
+        console.log(safeJson({ agent_id: data.agent_id, bind_url: data.bind_url, status: data.status, limits }));
+      } else {
+        console.log(`✅ Temporary XMemo memory enabled for this installation.\nThis is a limited sandbox, not a formal account.\nTemporary limits: up to ${limits.max_items} items; expires after ${formatDuration(limits.ttl_seconds)} without successful memory activity; maximum ${formatDuration(limits.max_lifetime_seconds)} from registration.\nComplete formal registration (recommended): ${sanitizeTerminalText(data.bind_url)}\nDo not share this bind URL publicly. After the human claim, run "${SCRIPT_COMMAND} auth claim-confirm" to accept the formal credential.`);
+      }
+      process.exit(EXIT_CODE.SUCCESS);
+    } catch (e) {
+      console.error('Temporary registration failed:', e.message);
+      process.exit(exitCodeForError(e));
+    }
+  }
+
+  // 2. LOGOUT
+  if (command === 'logout') {
+    const credential = await getStoredCredential();
+    const token = credential?.token;
+    if (!token) {
+      console.log('No active login found.');
+      process.exit(EXIT_CODE.SUCCESS);
+    }
+
+    if (['openclaw-secret', 'vault'].includes(credential.storage) || (credential.storage === 'environment' && !options.revokeEnvironmentToken)) {
+      if (credential.storage === 'openclaw-secret' && options.revokeEnvironmentToken) {
+        console.error('Error: OpenClaw secret sentinels are managed by OpenClaw and cannot be revoked remotely. Use "openclaw secrets delete" or the OpenClaw Control UI to manage secrets.');
+        process.exit(EXIT_CODE.USER_ERROR);
+      }
+      const isOc = credential.storage === 'openclaw-secret';
+      const isVault = credential.storage === 'vault';
+      const status = isOc ? 'openclaw_secret_unchanged' : isVault ? 'vault_credential_unchanged' : 'environment_credential_unchanged';
+      const source = isOc ? 'openclaw-secret' : isVault ? 'muse-vault' : 'XMEMO_KEY';
+      if (options.json) {
+        console.log(safeJson({ status, credential_source: source, remote_revoked: false, local_file_removed: false }));
+      } else if (isOc) {
+        console.log('XMemo credential is provided by OpenClaw (openclaw-secret). No remote token was revoked and no local credential file was changed.\nTo disconnect or rotate, use "openclaw secrets delete" or the OpenClaw Control UI.');
+      } else if (isVault) {
+        console.log('XMemo credential is provided by Meta Muse (muse-vault). No remote token was revoked and no local credential file was changed.\nTo disconnect, remove the credential in Meta Muse.');
+      } else {
+        console.log('XMEMO_KEY is externally managed. No token was revoked and no local credential file was changed.\nUnset XMEMO_KEY in the launching environment to log out, or pass --revoke-environment-token to explicitly revoke that token.');
+      }
+      process.exit(EXIT_CODE.SUCCESS);
+    }
+
+    let remoteRevoked = false;
+    let revokeError = null;
+    try {
+      const revokeRes = await makeHttpRequest(options.baseUrl, '/v1/auth/token/revoke-self', 'POST', {}, {
+        'Authorization': `Bearer ${token}`
+      }, options.timeoutMs);
+      remoteRevoked = revokeRes.statusCode >= 200 && revokeRes.statusCode < 300;
+      if (!remoteRevoked) revokeError = `HTTP ${revokeRes.statusCode}`;
+    } catch (error) {
+      revokeError = sanitizeTerminalText(error.message);
+    }
+
+    let localFileRemoved = false;
+    if (credential.storage !== 'environment') {
+      try {
+        await fs.unlink(credentialsPath);
+        localFileRemoved = true;
+      } catch (error) {
+        if (error?.code !== 'ENOENT') throw error;
+      }
+    }
+
+    const result = {
+      status: remoteRevoked ? 'logged_out' : 'local_logout_completed',
+      credential_source: credential.storage === 'environment' ? 'XMEMO_KEY' : 'user-credential-file',
+      remote_revoked: remoteRevoked,
+      local_file_removed: localFileRemoved,
+      ...(revokeError ? { remote_revoke_error: revokeError } : {}),
+    };
+    if (options.json) {
+      console.log(safeJson(result));
+    } else if (credential.storage === 'environment') {
+      console.log(remoteRevoked
+        ? '✅ The externally managed XMEMO_KEY token was explicitly revoked. Unset XMEMO_KEY in the launching environment.'
+        : `The XMEMO_KEY token could not be revoked (${revokeError}). It remains externally managed.`);
+    } else if (remoteRevoked) {
+      console.log('✅ Logged out successfully. The remote token was revoked and the local credential file was removed.');
+    } else {
+      console.log(`Local credential file removed. Remote revocation could not be confirmed${revokeError ? ` (${revokeError})` : ''}.`);
+    }
+    process.exit(EXIT_CODE.SUCCESS);
+  }
+}

package/skill/scripts/commands/auth-manage.mjs

@@ -0,0 +1,201 @@
+import {
+  credentialsPath,
+  SCRIPT_COMMAND,
+  EXIT_CODE,
+  exitCodeForError,
+} from '../lib/core.mjs';
+
+import {
+  readStdin,
+} from '../lib/cli-input.mjs';
+
+import {
+  printUsage,
+} from '../lib/help.mjs';
+
+import {
+  getStoredCredential,
+  requirePlaintextStorageConsent,
+  plaintextStorageAllowed,
+  saveToken,
+  claimStatus,
+} from '../lib/auth-state.mjs';
+
+import {
+  isOpenClawSentinel,
+} from '../lib/openclaw-egress.mjs';
+
+import {
+  makeHttpRequest,
+  parseJsonResponse,
+  apiErrorMessage,
+  safeJson,
+  sanitizeTerminalText,
+} from '../lib/api.mjs';
+
+export async function handleAuthManage(ctx) {
+  const { subcommand, options, flags } = ctx;
+
+  if (subcommand === 'status') {
+    const credential = await getStoredCredential();
+    const token = credential?.token;
+    if (!token) {
+      if (options.json) {
+        console.log(JSON.stringify({ status: 'logged_out' }));
+      } else {
+        console.log('Status: Logged out.');
+      }
+      process.exit(EXIT_CODE.SUCCESS);
+    }
+    
+    const credentialSource = credential?.storage === 'openclaw-secret'
+      ? 'openclaw-secret'
+      : credential?.storage === 'vault'
+        ? 'muse-vault'
+        : credential?.storage === 'environment'
+          ? 'XMEMO_KEY'
+          : credential?.credential_type === 'temporary'
+            ? 'temporary-user-credential-file'
+            : 'formal-user-credential-file';
+    if (options.verify) {
+      try {
+        const res = await makeHttpRequest(options.baseUrl, '/v1/auth/token/validate', 'GET', null, {
+          'Authorization': `Bearer ${token}`
+        }, options.timeoutMs);
+        const data = parseJsonResponse(res, 'Token verification');
+        if (res.statusCode === 200) {
+          if (options.json) {
+            console.log(safeJson({ status: 'valid', credential_source: credentialSource, scopes: data.scopes, setup_state: data.setup_state }));
+          } else {
+            const scopes = Array.isArray(data.scopes) ? data.scopes : [];
+            console.log(`Status: Logged in (verified)\nCredential Source: ${credentialSource}\nScopes: ${scopes.join(', ')}`);
+          }
+        } else {
+          if (options.json) {
+            console.log(safeJson({ status: 'invalid', credential_source: credentialSource }));
+          } else {
+            console.error(`Status: Invalid or expired token.${data ? ` ${apiErrorMessage(data, '')}` : ''}`);
+          }
+          const exitCode = res.statusCode >= 500 ? EXIT_CODE.SERVER_ERROR : EXIT_CODE.AUTH_ERROR;
+          process.exit(exitCode);
+        }
+      } catch (e) {
+        console.error('Verification error:', e.message);
+        process.exit(exitCodeForError(e));
+      }
+    } else {
+      if (options.json) {
+        console.log(safeJson({ status: 'logged_in', credential_source: credentialSource }));
+      } else {
+        const kind = credential?.credential_type === 'temporary' ? 'Temporary access' : 'Logged in';
+        console.log(`Status: ${kind}\nCredential Source: ${credentialSource}`);
+      }
+    }
+    process.exit(EXIT_CODE.SUCCESS);
+  }
+  
+  if (subcommand === 'add') {
+    if (flags['from-stdin'] !== undefined || process.argv.includes('--from-stdin')) {
+      try {
+        requirePlaintextStorageConsent(options, 'auth add');
+      } catch (e) {
+        console.error(`Credential storage refused: ${e.message}`);
+        process.exit(EXIT_CODE.USER_ERROR);
+      }
+      const token = await readStdin();
+      if (!token) {
+        console.error('Error: Stdin did not provide a token.');
+        process.exit(EXIT_CODE.USER_ERROR);
+      }
+      if (typeof token === 'string' && token.startsWith('hsurr:')) {
+        console.error('Error: Refusing to store Meta Muse surrogate token. Surrogate tokens are dynamic and managed by Meta Muse.');
+        process.exit(EXIT_CODE.USER_ERROR);
+      }
+      if (isOpenClawSentinel(token)) {
+        console.error('Error: Refusing to store OpenClaw sentinel token. Sentinels are dynamic and managed by OpenClaw.');
+        process.exit(EXIT_CODE.USER_ERROR);
+      }
+      try {
+        await saveToken(token, { credential_type: 'formal' }, { allowPlaintext: options.allowPlaintext, warn: true });
+        console.log(`✅ Credential stored in the explicitly approved user credential file: ${credentialsPath}`);
+        console.log('Token value was not printed. Project files were not modified.');
+        process.exit(EXIT_CODE.SUCCESS);
+      } catch (err) {
+        console.error('Failed to save credentials file:', err.message);
+        process.exit(EXIT_CODE.USER_ERROR);
+      }
+    } else {
+      console.error(`Error: Run "${SCRIPT_COMMAND} auth add --from-stdin --allow-plaintext" to supply and explicitly store a token.`);
+      process.exit(EXIT_CODE.USER_ERROR);
+    }
+  }
+
+  if (subcommand === 'claim-status' || subcommand === 'claim-confirm' || subcommand === 'claim-deny') {
+    const credential = await getStoredCredential();
+    if (!credential?.token || credential.credential_type !== 'temporary') {
+      console.error('Error: Claim commands require a locally stored temporary credential from "register".');
+      process.exit(EXIT_CODE.USER_ERROR);
+    }
+    try {
+      if (subcommand === 'claim-deny') {
+        const denyRes = await makeHttpRequest(options.baseUrl, '/v1/agents/bind/deny-current-user', 'POST', {}, {
+          Authorization: `Bearer ${credential.token}`,
+        }, options.timeoutMs);
+        const denyData = parseJsonResponse(denyRes, 'Claim denial');
+        if (denyRes.statusCode < 200 || denyRes.statusCode >= 300) {
+          const err = new Error(apiErrorMessage(denyData, safeJson(denyData)));
+          err.statusCode = denyRes.statusCode;
+          throw err;
+        }
+        const allowPlaintext = plaintextStorageAllowed(options, credential);
+        await saveToken(credential.token, {
+          credential_type: 'temporary',
+          agent_id: credential.agent_id,
+          bind_url: credential.bind_url,
+          registration_reason: credential.registration_reason,
+        }, { allowPlaintext, warn: options.allowPlaintext && !credential.plaintext_storage_consent });
+        if (options.json) {
+          console.log(safeJson(denyData));
+        } else {
+          console.log('Pending account binding declined. The credential remains limited to isolated temporary memory; formal account login is still recommended.');
+        }
+        process.exit(EXIT_CODE.SUCCESS);
+      }
+      const status = await claimStatus(options.baseUrl, credential, options);
+      if (subcommand === 'claim-confirm' && !status.formal_token) {
+        const confirmation_token = status.confirmation_token || credential.pending_confirmation_token;
+        if (!confirmation_token) {
+          console.error(`No pending human claim confirmation is available. Current status: ${sanitizeTerminalText(status.status || 'unknown')}. Open the stored bind URL first: ${sanitizeTerminalText(credential.bind_url || '(unavailable)')}`);
+          process.exit(EXIT_CODE.USER_ERROR);
+        }
+        const confirmRes = await makeHttpRequest(options.baseUrl, '/v1/agents/bind/confirm-current-user', 'POST', { confirmation_token }, {
+          Authorization: `Bearer ${credential.token}`,
+        }, options.timeoutMs);
+        const confirmData = parseJsonResponse(confirmRes, 'Claim confirmation');
+        if (confirmRes.statusCode < 200 || confirmRes.statusCode >= 300) {
+          const err = new Error(apiErrorMessage(confirmData, safeJson(confirmData)));
+          err.statusCode = confirmRes.statusCode;
+          throw err;
+        }
+        if (credential.pending_confirmation_token) {
+          const allowPlaintext = plaintextStorageAllowed(options, credential);
+          await saveToken(credential.token, {
+            credential_type: 'temporary',
+            agent_id: credential.agent_id,
+            bind_url: credential.bind_url,
+            registration_reason: credential.registration_reason,
+          }, { allowPlaintext, warn: options.allowPlaintext && !credential.plaintext_storage_consent });
+        }
+        await claimStatus(options.baseUrl, credential, options);
+      }
+      process.exit(EXIT_CODE.SUCCESS);
+    } catch (e) {
+      console.error('Claim flow failed:', e.message);
+      process.exit(exitCodeForError(e));
+    }
+  }
+  
+  console.error(`Unknown auth subcommand: ${subcommand || '(missing)'}`);
+  printUsage('auth');
+  process.exit(EXIT_CODE.USER_ERROR);
+}