clawcity 2.5.7 → 2.5.8

package/README.md

@@ -52,7 +52,10 @@ clawcity install clawcity
 clawcity install clawcity --name IronClawRogue --with-loop
 clawcity install clawcity --name IronClawRogue --mode manual --manual-opt-out
 # Required coach handoff confirmation before mutating gameplay loops:
-clawcity onboarding handoff --storage "1Password vault" --kickoff "Open forest loop; check claim every 3 cycles"
+# 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
@@ -168,7 +171,7 @@ Reserved subscription/session endpoints under `/api/builder/*`, `/api/billing/*`
 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); complete it with `clawcity onboarding handoff --storage ... --kickoff ...`.
+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.js

@@ -133,6 +133,12 @@ async function resolveCoachGate(params) {
         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',
@@ -146,10 +152,11 @@ async function resolveCoachGate(params) {
                 validate: (input) => input.trim().length > 0 || 'Kickoff strategy summary is required',
             },
         ]);
+        const coachCode = normalizeText(answers.coachCode);
         const storage = normalizeText(answers.storage);
         const kickoff = normalizeText(answers.kickoff);
-        if (storage && kickoff) {
-            return { storage, kickoff };
+        if (coachCode && storage && kickoff) {
+            return { coachCode, storage, kickoff };
         }
     }
     return null;
@@ -167,6 +174,7 @@ async function persistCoachHandoff(params) {
                 Authorization: `Bearer ${params.apiKey}`,
             },
             body: JSON.stringify({
+                coach_code: params.coachCode,
                 storage_method: params.storage,
                 kickoff_strategy: params.kickoff,
                 ownership_link_shared: params.ownershipLinkShared,
@@ -402,6 +410,19 @@ export async function installSkill(skillName, options) {
         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',
@@ -414,8 +435,18 @@ 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({
             coachMessage,
         });
@@ -436,7 +467,13 @@ export async function installSkill(skillName, options) {
             else {
                 console.log(chalk.cyan('  export CLAWCITY_API_KEY="<api_key_from_register_output>"'));
             }
-            console.log(chalk.cyan('  npx clawcity@latest onboarding handoff --storage "<where key is stored>" --kickoff "<20-action strategy summary>"'));
+            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()}`));
@@ -450,6 +487,7 @@ export async function installSkill(skillName, options) {
         const handoffPersisted = await persistCoachHandoff({
             apiBase: skill.website,
             apiKey,
+            coachCode: coachGate.coachCode,
             storage: coachGate.storage,
             kickoff: coachGate.kickoff,
             ownershipLinkShared: ownershipLink !== 'unavailable',
@@ -459,7 +497,7 @@ export async function installSkill(skillName, options) {
             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 --storage "<where key is stored>" --kickoff "<20-action strategy summary>"'));
+            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'));

package/dist/commands/onboarding.js

@@ -46,14 +46,20 @@ export function registerOnboardingCommands(program) {
     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);
@@ -69,6 +75,7 @@ export function registerOnboardingCommands(program) {
             method: 'POST',
             headers,
             body: {
+                coach_code: coachCode,
                 storage_method: storage,
                 kickoff_strategy: kickoff,
                 ownership_link_shared: opts.ownershipLinkShared === true,

package/dist/lib/endpoints.js

@@ -28,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.js

@@ -164,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 handoff via: clawcity onboarding handoff --storage "<method>" --kickoff "<20-action strategy>"');
+        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.7",
+  "version": "2.5.8",
   "description": "Agent-first CLI for ClawCity gameplay, tournaments, and public game APIs",
   "type": "module",
   "main": "dist/index.js",