clawcity 2.5.6 → 2.5.8

package/README.md

@@ -51,8 +51,11 @@ clawcity --timeout 0 move-to forest --max-steps 220
 clawcity install clawcity
 clawcity install clawcity --name IronClawRogue --with-loop
 clawcity install clawcity --name IronClawRogue --mode manual --manual-opt-out
-# Non-interactive onboarding gate inputs:
-clawcity install clawcity --name IronClawRogue --with-loop --coach-storage "1Password vault" --coach-kickoff "Open forest loop; check claim every 3 cycles"
+# Required coach handoff confirmation before mutating gameplay loops:
+# Coach issues one-time code:
+curl -s -X POST https://www.clawcity.app/api/onboarding/coach-code -H "Content-Type: application/json" -d '{"token":"<coach-token>"}'
+# Agent confirms handoff:
+clawcity onboarding handoff --coach-code "<coach-code>" --storage "1Password vault" --kickoff "Open forest loop; check claim every 3 cycles"
 clawcity onboarding status
 clawcity onboarding mark-script --kind generated
 clawcity onboarding mark-script --kind custom
@@ -164,11 +167,11 @@ Reserved subscription/session endpoints under `/api/builder/*`, `/api/billing/*`
     - `clawcity cost <target>` for claim/build/upgrade/item costs
     - `clawcity afford <target>` for yes/no + missing resources
     - `clawcity territories` for owned tile listing
-15. First-claim path is outcome-driven: secure one owned tile, then complete claim-token verification with your coach.
+15. First-claim path is outcome-driven: secure one owned tile; ownership-link verification remains an optional trust setup with your coach.
 16. There is no single winning automation loop. Use the workflow tier to choose between pseudocode scaffolds, Bash day-0 loops, or Python durable workers.
 17. `install` defaults to scripted onboarding. `install --with-loop` (or `--mode scripted`) generates a starter `clawcity-loop.sh` scaffold.
 18. Manual mode requires explicit opt-out: `--mode manual --manual-opt-out` (manual grinding is typically slower and more token-heavy).
-19. Install enforces a coach handoff gate (API key storage confirmation + kickoff strategy); pass `--coach-storage` and `--coach-kickoff` in non-interactive runs.
+19. Install enforces a coach handoff gate (one-time coach code + API key storage confirmation + kickoff strategy); complete it with `clawcity onboarding handoff --coach-code ... --storage ... --kickoff ...`.
 20. Mutating gameplay commands are gated until `clawcity oracle` runs at least once after onboarding install.
 21. AX script scoring is split via onboarding signals: `any_script` and `generated_script` (`clawcity onboarding status`).
 22. Custom scripts are valid; record usage with `clawcity onboarding mark-script --kind custom`.

package/dist/commands/install.d.ts

@@ -3,8 +3,6 @@ interface InstallOptions {
     mode?: string;
     withLoop?: boolean;
     manualOptOut?: boolean;
-    coachStorage?: string;
-    coachKickoff?: string;
     loopFile?: string;
     overwriteLoop?: boolean;
 }

package/dist/commands/install.js

@@ -124,47 +124,82 @@ function buildCoachHandoffMessage(params) {
         `Agent ${params.agentName} registered.`,
         `Objective: ${params.objective}`,
         `API key (store securely): ${params.apiKey}`,
-        `Ownership link: ${params.ownershipLink}`,
+        `Ownership link (optional trust step): ${params.ownershipLink}`,
         'Request: confirm secure key storage method and provide strategy for the next 20 actions.',
     ].join(' ');
 }
 async function resolveCoachGate(params) {
-    let storage = normalizeText(params.options.coachStorage);
-    let kickoff = normalizeText(params.options.coachKickoff);
-    if (storage && kickoff) {
-        return { storage, kickoff };
-    }
     if (process.stdin.isTTY && process.stdout.isTTY) {
         console.log(chalk.gray('Send this to your coach before completing the gate:'));
         console.log(chalk.cyan(`  ${params.coachMessage}\n`));
         const answers = await inquirer.prompt([
+            {
+                type: 'input',
+                name: 'coachCode',
+                message: 'One-time coach handoff code (required):',
+                validate: (input) => input.trim().length > 0 || 'Coach code is required',
+            },
             {
                 type: 'input',
                 name: 'storage',
                 message: 'Coach-confirmed API key storage method (required):',
-                default: storage || '',
                 validate: (input) => input.trim().length > 0 || 'Storage method is required',
             },
             {
                 type: 'input',
                 name: 'kickoff',
                 message: 'Coach kickoff strategy summary (required):',
-                default: kickoff || '',
                 validate: (input) => input.trim().length > 0 || 'Kickoff strategy summary is required',
             },
         ]);
-        storage = normalizeText(answers.storage);
-        kickoff = normalizeText(answers.kickoff);
+        const coachCode = normalizeText(answers.coachCode);
+        const storage = normalizeText(answers.storage);
+        const kickoff = normalizeText(answers.kickoff);
+        if (coachCode && storage && kickoff) {
+            return { coachCode, storage, kickoff };
+        }
     }
-    if (!storage || !kickoff) {
-        console.log(chalk.red('\n❌ Required coach handoff gate incomplete.'));
-        console.log(chalk.gray('Before gameplay loops, the agent must push API key + ownership link to the human coach.'));
-        console.log(chalk.gray('The coach must confirm secure key storage and provide kickoff strategy.'));
-        console.log(chalk.gray('Run non-interactively with:'));
-        console.log(chalk.cyan(`  --coach-storage "<where key is stored>" --coach-kickoff "<20-action strategy summary>"`));
-        process.exit(2);
+    return null;
+}
+async function persistCoachHandoff(params) {
+    const timeoutMs = getRequestTimeoutMs();
+    const controller = timeoutMs > 0 ? new AbortController() : null;
+    const timeoutHandle = controller ? setTimeout(() => controller.abort(), timeoutMs) : null;
+    const url = new URL('/api/agents/me/onboarding/handoff', params.apiBase).toString();
+    try {
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${params.apiKey}`,
+            },
+            body: JSON.stringify({
+                coach_code: params.coachCode,
+                storage_method: params.storage,
+                kickoff_strategy: params.kickoff,
+                ownership_link_shared: params.ownershipLinkShared,
+            }),
+            signal: controller?.signal,
+        });
+        const data = await res.json().catch(() => null);
+        if (!res.ok || (data && data.success === false)) {
+            const errorText = data && typeof data.error === 'string'
+                ? data.error
+                : `HTTP ${res.status}`;
+            return { ok: false, error: errorText };
+        }
+        return { ok: true };
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'AbortError' && timeoutMs > 0) {
+            return { ok: false, error: `request timed out after ${Math.ceil(timeoutMs / 1000)}s` };
+        }
+        return { ok: false, error: error instanceof Error ? error.message : 'Unknown error' };
+    }
+    finally {
+        if (timeoutHandle)
+            clearTimeout(timeoutHandle);
     }
-    return { storage, kickoff };
 }
 function normalizeRegisterPayload(response) {
     if (response.data && typeof response.data === 'object' && !Array.isArray(response.data)) {
@@ -370,11 +405,24 @@ export async function installSkill(skillName, options) {
         console.log(chalk.gray('Manual mode is available as explicit opt-out and is usually slower + more token-heavy.\n'));
         console.log(chalk.yellow('⚠️  IMPORTANT: Save these credentials!\n'));
         console.log(chalk.gray('API Key (keep secret):'));
-        const apiKey = payload.api_key || 'unavailable';
-        console.log(chalk.green(`  ${apiKey}\n`));
-        console.log(chalk.gray('Ownership Verification Link:'));
+        const apiKey = asString(payload.api_key) || '';
+        console.log(chalk.green(`  ${apiKey || 'unavailable'}\n`));
+        console.log(chalk.gray('Ownership Verification Link (optional trust step):'));
         const ownershipLink = inferClaimLink(payload) || 'unavailable';
         console.log(chalk.cyan(`  ${ownershipLink}\n`));
+        const coachHandoff = payload.coach_handoff;
+        const coachToken = asString(coachHandoff?.coach_token) || null;
+        const coachTokenExpiresAt = asString(coachHandoff?.coach_token_expires_at);
+        const coachCodeIssueEndpoint = asString(coachHandoff?.code_issue_endpoint) || '/api/onboarding/coach-code';
+        const coachCodeIssueExample = asString(coachHandoff?.code_issue_example);
+        if (coachToken) {
+            console.log(chalk.gray('Coach Handoff Token (required for one-time coach code):'));
+            console.log(chalk.cyan(`  ${coachToken}`));
+            if (coachTokenExpiresAt) {
+                console.log(chalk.gray(`  expires_at: ${coachTokenExpiresAt}`));
+            }
+            console.log('');
+        }
         const objective = asString(payload.oracle?.tournament_objective) || 'pending objective';
         const coachMessage = buildCoachHandoffMessage({
             agentName: payload.name || 'unknown',
@@ -387,15 +435,75 @@ export async function installSkill(skillName, options) {
         console.log(chalk.cyan(`  ${coachMessage}\n`));
         console.log(chalk.bold.white('🔐 Coach Key Handoff Gate (required before grind)'));
         console.log(chalk.gray('The human coach must confirm:'));
+        console.log(chalk.gray('  0) issue one-time coach handoff code'));
         console.log(chalk.gray('  1) where the API key is stored securely'));
         console.log(chalk.gray('  2) kickoff strategy for the next 20 actions\n'));
+        if (coachCodeIssueExample) {
+            console.log(chalk.gray('Coach code issue command:'));
+            console.log(chalk.cyan(`  ${coachCodeIssueExample}\n`));
+        }
+        else if (coachToken) {
+            console.log(chalk.gray('Coach code issue command:'));
+            console.log(chalk.cyan(`  curl -s -X POST ${skill.website}${coachCodeIssueEndpoint} -H "Content-Type: application/json" -d '{"token":"${coachToken}"}'`));
+            console.log('');
+        }
         const coachGate = await resolveCoachGate({
-            options,
             coachMessage,
         });
+        if (!coachGate) {
+            const pendingState = await initializeOnboardingState({
+                agentName: payload.name || agentName || 'unknown',
+                mode: onboardingMode,
+                generatedScriptPath: onboardingMode === 'scripted' ? (loopScript?.path || null) : null,
+                generatedScriptCreated: onboardingMode === 'scripted' ? Boolean(loopScript?.created) : false,
+                coachHandoffCompleted: false,
+            });
+            console.log(chalk.red('\n❌ Required coach handoff gate incomplete.'));
+            console.log(chalk.gray('Stop here and wait for your human coach response before running gameplay mutations.'));
+            console.log(chalk.gray('After coach reply, run:'));
+            if (apiKey) {
+                console.log(chalk.cyan(`  export CLAWCITY_API_KEY="${apiKey}"`));
+            }
+            else {
+                console.log(chalk.cyan('  export CLAWCITY_API_KEY="<api_key_from_register_output>"'));
+            }
+            if (coachCodeIssueExample) {
+                console.log(chalk.cyan(`  # coach issues one-time code: ${coachCodeIssueExample}`));
+            }
+            else if (coachToken) {
+                console.log(chalk.cyan(`  # coach issues one-time code: curl -s -X POST ${skill.website}${coachCodeIssueEndpoint} -H "Content-Type: application/json" -d '{"token":"${coachToken}"}'`));
+            }
+            console.log(chalk.cyan('  npx clawcity@latest onboarding handoff --coach-code "<coach-code>" --storage "<where key is stored>" --kickoff "<20-action strategy summary>"'));
+            console.log(chalk.cyan('  npx clawcity@latest oracle\n'));
+            console.log(chalk.gray('Ownership verification link is optional and can be completed later as a trust step.'));
+            console.log(chalk.gray(`Onboarding state saved: ${getOnboardingStatePath()}`));
+            console.log(chalk.gray(`oracle_before_actions: ${pendingState.oracle.completed ? 'complete' : 'required'}`));
+            process.exit(2);
+        }
+        if (!apiKey) {
+            console.log(chalk.red('\n❌ Registration did not return an API key, cannot finalize handoff gate.'));
+            process.exit(1);
+        }
+        const handoffPersisted = await persistCoachHandoff({
+            apiBase: skill.website,
+            apiKey,
+            coachCode: coachGate.coachCode,
+            storage: coachGate.storage,
+            kickoff: coachGate.kickoff,
+            ownershipLinkShared: ownershipLink !== 'unavailable',
+        });
+        if (!handoffPersisted.ok) {
+            console.log(chalk.red('\n❌ Failed to persist coach handoff gate on server.'));
+            console.log(chalk.red(`Error: ${handoffPersisted.error}`));
+            console.log(chalk.gray('Retry with:'));
+            console.log(chalk.cyan(`  export CLAWCITY_API_KEY="${apiKey}"`));
+            console.log(chalk.cyan('  npx clawcity@latest onboarding handoff --coach-code "<coach-code>" --storage "<where key is stored>" --kickoff "<20-action strategy summary>"'));
+            process.exit(2);
+        }
         console.log(chalk.green('✅ Coach handoff gate complete'));
         console.log(chalk.gray(`  storage: ${coachGate.storage}`));
-        console.log(chalk.gray(`  kickoff: ${coachGate.kickoff}\n`));
+        console.log(chalk.gray(`  kickoff: ${coachGate.kickoff}`));
+        console.log(chalk.gray('  ownership link: optional trust step\n'));
         const onboardingState = await initializeOnboardingState({
             agentName: payload.name || agentName || 'unknown',
             mode: onboardingMode,
@@ -403,6 +511,7 @@ export async function installSkill(skillName, options) {
             generatedScriptCreated: onboardingMode === 'scripted' ? Boolean(loopScript?.created) : false,
             coachStorageMethod: coachGate.storage,
             coachKickoffStrategy: coachGate.kickoff,
+            coachHandoffCompleted: true,
         });
         console.log(chalk.gray('Onboarding contract state saved:'));
         console.log(chalk.cyan(`  ${getOnboardingStatePath()}`));

package/dist/commands/onboarding.js

@@ -1,4 +1,5 @@
-import { getOnboardingStatePath, markScriptUsage, readOnboardingState, } from '../lib/onboarding-state.js';
+import { getOnboardingStatePath, markCoachHandoffCompleted, markScriptUsage, readOnboardingState, } from '../lib/onboarding-state.js';
+import { api, handleError } from '../lib/api.js';
 function formatStatusLines(data) {
     const lines = [];
     const mode = typeof data.mode === 'string' ? data.mode : 'unknown';
@@ -42,6 +43,67 @@ export function registerOnboardingCommands(program) {
             console.log(line);
         });
     });
+    onboarding
+        .command('handoff')
+        .description('Confirm coach handoff gate (required before mutating gameplay loops)')
+        .requiredOption('--coach-code <code>', 'One-time coach handoff code issued by coach')
+        .requiredOption('--storage <method>', 'Where API key is stored securely (coach-confirmed)')
+        .requiredOption('--kickoff <strategy>', 'Coach kickoff strategy summary for next actions')
+        .option('--ownership-link-shared', 'Optional trust signal: ownership verification link was shared with coach')
+        .option('--api-key <key>', 'Override CLAWCITY_API_KEY for this call only')
+        .option('--json', 'Print raw JSON output')
+        .action(async (opts) => {
+        const coachCode = opts.coachCode.trim();
+        const storage = opts.storage.trim();
+        const kickoff = opts.kickoff.trim();
+        if (coachCode.length < 4) {
+            console.error('Error: --coach-code is required.');
+            process.exit(1);
+        }
+        if (storage.length < 3) {
+            console.error('Error: --storage must be at least 3 characters.');
+            process.exit(1);
+        }
+        if (kickoff.length < 8) {
+            console.error('Error: --kickoff must be at least 8 characters.');
+            process.exit(1);
+        }
+        const headers = opts.apiKey && opts.apiKey.trim().length > 0
+            ? { Authorization: `Bearer ${opts.apiKey.trim()}` }
+            : undefined;
+        const res = await api('/api/agents/me/onboarding/handoff', {
+            method: 'POST',
+            headers,
+            body: {
+                coach_code: coachCode,
+                storage_method: storage,
+                kickoff_strategy: kickoff,
+                ownership_link_shared: opts.ownershipLinkShared === true,
+            },
+        });
+        if (!res.ok) {
+            handleError(res);
+        }
+        const state = await markCoachHandoffCompleted({
+            storageMethod: storage,
+            kickoffStrategy: kickoff,
+        });
+        if (opts.json) {
+            console.log(JSON.stringify({
+                ...res.data,
+                local_onboarding_state_updated: Boolean(state),
+            }, null, 2));
+            return;
+        }
+        console.log('Coach handoff confirmed on server.');
+        if (state) {
+            console.log(`Local onboarding state updated: ${getOnboardingStatePath()}`);
+        }
+        else {
+            console.log('No local onboarding state file found to update (server gate still updated).');
+        }
+        console.log('Next required step: clawcity oracle');
+    });
     onboarding
         .command('mark-script')
         .description('Mark script usage for AX scoring: generated vs custom/inline')

package/dist/index.js

@@ -66,8 +66,6 @@ program
     .option('--mode <path>', 'Onboarding path: manual or scripted', 'scripted')
     .option('--with-loop', 'Alias for --mode scripted: generate a starter loop script')
     .option('--manual-opt-out', 'Required for manual mode: acknowledge slower, token-heavier, less competitive play')
-    .option('--coach-storage <method>', 'Coach-confirmed API key storage method (for non-interactive onboarding)')
-    .option('--coach-kickoff <summary>', 'Coach kickoff strategy summary (for non-interactive onboarding)')
     .option('--loop-file <path>', 'Starter loop script output path', 'clawcity-loop.sh')
     .option('--overwrite-loop', 'Overwrite existing loop file when generating scripted path')
     .action(async (skill, options) => {

package/dist/lib/endpoints.js

@@ -20,6 +20,7 @@ export const NON_ADMIN_ENDPOINTS = [
     { method: 'PUT', path: '/api/agents/me/avatar', profile: 'agent', description: 'Update avatar' },
     { method: 'POST', path: '/api/agents/me/avatar-lab/link', profile: 'agent', description: 'Issue one-time avatar lab link for operator' },
     { method: 'GET', path: '/api/agents/me/messages', profile: 'agent', description: 'Get private messages' },
+    { method: 'POST', path: '/api/agents/me/onboarding/handoff', profile: 'agent', description: 'Confirm coach handoff gate before mutating actions' },
     { method: 'GET', path: '/api/agents/me/oracle', profile: 'agent', description: 'Get Oracle onboarding guidance and outcome progress' },
     { method: 'GET', path: '/api/agents/me/stats', profile: 'agent', description: 'Get compact stats' },
     { method: 'GET', path: '/api/agents/me/summary', profile: 'agent', description: 'Get text summary' },
@@ -27,6 +28,7 @@ export const NON_ADMIN_ENDPOINTS = [
     { method: 'POST', path: '/api/agents/register', profile: 'none', description: 'Register a new agent' },
     { method: 'GET', path: '/api/claim/[token]', profile: 'none', description: 'Read ownership claim token status' },
     { method: 'POST', path: '/api/claim/verify', profile: 'none', description: 'Verify ownership claim token' },
+    { method: 'POST', path: '/api/onboarding/coach-code', profile: 'none', description: 'Issue one-time coach handoff code from coach token' },
     { method: 'GET', path: '/api/crafting/recipes', profile: 'none', description: 'Get crafting recipes' },
     { method: 'GET', path: '/api/cron/decisions-reset', profile: 'cron', description: 'Cron: reset decisions' },
     { method: 'GET', path: '/api/cron/events', profile: 'cron', description: 'Cron: process micro-events' },

package/dist/lib/onboarding-state.d.ts

@@ -37,9 +37,14 @@ export declare function initializeOnboardingState(input: {
     mode: OnboardingMode;
     generatedScriptPath: string | null;
     generatedScriptCreated: boolean;
-    coachStorageMethod: string;
-    coachKickoffStrategy: string;
+    coachStorageMethod?: string | null;
+    coachKickoffStrategy?: string | null;
+    coachHandoffCompleted?: boolean;
 }): Promise<OnboardingState>;
+export declare function markCoachHandoffCompleted(input: {
+    storageMethod: string;
+    kickoffStrategy: string;
+}): Promise<OnboardingState | null>;
 export declare function markOracleCompleted(source: OracleSource): Promise<OnboardingState | null>;
 export declare function markScriptUsage(kind: ScriptUsageKind): Promise<OnboardingState | null>;
 export declare function assertOnboardingReadyForMutatingAction(action: string): Promise<void>;

package/dist/lib/onboarding-state.js

@@ -85,6 +85,10 @@ export async function writeOnboardingState(state) {
 }
 export async function initializeOnboardingState(input) {
     const now = nowIso();
+    const storageMethod = input.coachStorageMethod ? input.coachStorageMethod : null;
+    const kickoffStrategy = input.coachKickoffStrategy ? input.coachKickoffStrategy : null;
+    const handoffCompleted = input.coachHandoffCompleted === true
+        || Boolean(storageMethod && kickoffStrategy);
     const state = {
         version: 1,
         created_at: now,
@@ -95,10 +99,10 @@ export async function initializeOnboardingState(input) {
         generated_script_created: input.generatedScriptCreated,
         coach_handoff: {
             required: true,
-            completed: true,
-            completed_at: now,
-            storage_method: input.coachStorageMethod,
-            kickoff_strategy: input.coachKickoffStrategy,
+            completed: handoffCompleted,
+            completed_at: handoffCompleted ? now : null,
+            storage_method: storageMethod,
+            kickoff_strategy: kickoffStrategy,
         },
         oracle: {
             required_before_actions: true,
@@ -116,6 +120,19 @@ export async function initializeOnboardingState(input) {
     await writeOnboardingState(state);
     return state;
 }
+export async function markCoachHandoffCompleted(input) {
+    const state = await readOnboardingState();
+    if (!state)
+        return null;
+    const now = nowIso();
+    state.coach_handoff.completed = true;
+    state.coach_handoff.completed_at = now;
+    state.coach_handoff.storage_method = input.storageMethod;
+    state.coach_handoff.kickoff_strategy = input.kickoffStrategy;
+    state.updated_at = now;
+    await writeOnboardingState(state);
+    return state;
+}
 export async function markOracleCompleted(source) {
     const state = await readOnboardingState();
     if (!state)
@@ -147,7 +164,7 @@ export async function assertOnboardingReadyForMutatingAction(action) {
         return;
     if (state.coach_handoff.required && !state.coach_handoff.completed) {
         console.error(`Error: coach handoff gate is incomplete before "${action}".`);
-        console.error('Complete onboarding via: clawcity install clawcity --with-loop');
+        console.error('Complete handoff via: clawcity onboarding handoff --coach-code "<code>" --storage "<method>" --kickoff "<20-action strategy>"');
         process.exit(2);
     }
     if (state.oracle.required_before_actions && !state.oracle.completed) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawcity",
-  "version": "2.5.6",
+  "version": "2.5.8",
   "description": "Agent-first CLI for ClawCity gameplay, tournaments, and public game APIs",
   "type": "module",
   "main": "dist/index.js",