cloud-bump

name	cloud-bump
description	claude.ai の cloud 環境の init_script を内部 API で更新し、 環境スナップショットの再構築を発火させる。 Claude Code で /cloud-bump、Codex で $cloud-bump と入力したとき、または dotfiles の main にマージした変更が cloud 配信対象 (cloud-setup.yaml の paths) に触れていたときに使用する。 dotfiles を変更する PR を作成するときも、マージ後の bump の要否判定と予告のために使用する。
model	sonnet
allowed-tools	mcp__claude-in-chrome__javascript_tool

/cloud-bump

cloud 環境の setup script は毎セッション走らない。環境スナップショットの再構築時にだけ走り、再構築のトリガーは Setup script 欄の変更・allowed network hosts の変更・約 7 日のキャッシュ失効だけ (Environment caching)。main にマージして tarball が再デプロイされても、bump しない限り新規セッションは最大 7 日前のスナップショットで起動する。「マージされたので自動で反映済み」は誤り。設計の経緯は dotfiles#1347。

発火の判定

判定リストの正本は .github/workflows/cloud-setup.yaml の paths。スキルに書き写さず、workflow ファイルを読んで diff と突き合わせる。触れていなければ bump 不要と伝えて終わる。

bump してよいのは main にマージ済みの変更だけ。マージ前に bump すると古い main でスナップショットが焼き直されるだけになる。

cloud 配信対象に触れる PR を作成した時点では bump せず、マージ後に /cloud-bump の実行が必要なことを PR 作成の報告に書いて予告する。マージ後の bump は忘れられやすく、予告がないとユーザーはセッションを閉じてから気づけない。

権限

• Claude Code: JS 実行の許可は frontmatter の allowed-tools で与える。settings.json に javascript_tool の常時 allow を置かない。許可はこのスキルを起動したターンだけ有効で、次のユーザーメッセージで消れる (skills.md)。承認待ちでターンをまたいだら、POST の前にスキルを起動し直して許可を再適用する
• Codex: 最初に $chrome:control-chrome を読み、既存の Chrome セッションを選ぶ。本文の javascript_tool、read_network_requests、UI 操作を literal なツール名として呼ばず、browser-client の Playwright 評価・ネットワーク観察・クリックへ読み替える。最初に、page origin への GET と POST、ネットワーク観察を実行できる capability があるか確認する。capability が欠けていれば API 操作を試さず停止し、手動フォールバック URL を案内する。承認でターンをまたいだら $cloud-bump を再度読み、Chrome 接続と GET 結果を再確認してから POST する

どちらの環境でも POST 前の差分承認を省略しない。

Claude Code / Codex とも、claude.ai/code を開いた tab ID と bootstrap URL を最初に固定する。全 read、network 観察、fetch、click の直前に、固定した tab ID・https://claude.ai origin・/code で始まる path が一致することを確認する。不一致なら環境設定を送受信せず停止する。

Codex で承認を求めるときは、ユーザーへ「$cloud-bump 承認 と返信してください」と案内して turn を終える。次の発話で skill を明示的に再起動し、Chrome 接続と GET 結果が承認前と一致することを確認してから POST する。単なる「承認します」という返信を、skill を再読せずに処理しない。

init_script の更新 (内部 API)

claude.ai の未文書化 API で init_script を直接更新する。公式 API ではないため、動かなくなったら「エンドポイントの再発見」セクションの手順で調査し直す。

手順

Claude in Chrome で https://claude.ai/code を開き、JS でAPI を叩く。

GET で現在の環境設定を取得:

const assertClaudeContext = () => {
  if (location.origin !== 'https://claude.ai' || !location.pathname.startsWith('/code')) {
    throw new Error('unexpected tab origin or path');
  }
};
const canonicalize = value => Array.isArray(value)
  ? value.map(canonicalize)
  : value && typeof value === 'object'
    ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonicalize(value[key])]))
    : value;
const sha256 = async value => {
  const bytes = new TextEncoder().encode(JSON.stringify(canonicalize(value)));
  const digest = await crypto.subtle.digest('SHA-256', bytes);
  return [...new Uint8Array(digest)].map(byte => byte.toString(16).padStart(2, '0')).join('');
};
const orgId = '<network-log-derived-org-id>';
const envId = '<network-log-derived-env-id>';
if (!/^[A-Za-z0-9_-]{8,128}$/.test(orgId)) throw new Error('invalid orgId');
if (!/^[A-Za-z0-9_-]{8,128}$/.test(envId)) throw new Error('invalid envId');
const endpoint = `https://claude.ai/v1/environment_providers/private/organizations/${encodeURIComponent(orgId)}/environments/${encodeURIComponent(envId)}`;
assertClaudeContext();
const getResp = await fetch(endpoint);
if (!getResp.ok) throw new Error(`GET failed: ${getResp.status}`);
const env = await getResp.json();
const originalInit = String(env.config.init_script ?? '');
const now = new Date();
const pad = value => String(value).padStart(2, '0');
const proposedBumpLine = `# bump ${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ${pad(now.getHours())}:${pad(now.getMinutes())}`;
const snapshotDigest = await sha256(env);
({
  snapshotDigest,
  environmentId: env.environment_id ?? envId,
  name: env.name,
  currentBumpLine: originalInit.match(/^# bump \d{4}-\d{2}-\d{2} \d{2}:\d{2}(?=\n|$)/)?.[0] ?? null,
  proposedBumpLine
});

org_id と env_id は GET のレスポンス、または環境セレクタ操作時のネットワークログから取得する。環境が複数あるときは、どれを bump するかユーザーに確認する。

この GET call が返した snapshotDigest、環境名、現在の bump 行、proposedBumpLine だけを会話に控え、差分承認を得る。env 全体や config.environment を会話へ出さない。

承認後は別の JavaScript call で GET を再実行する。次の block の approvedSnapshotDigest と approvedBumpLine を承認済みの実値へ置換する。fresh GET の digest が一致した場合だけ、init_script の先頭行を更新して POST する。前の call の lexical binding は使わない。

const assertClaudeContext = () => {
  if (location.origin !== 'https://claude.ai' || !location.pathname.startsWith('/code')) {
    throw new Error('unexpected tab origin or path');
  }
};
const canonicalize = value => Array.isArray(value)
  ? value.map(canonicalize)
  : value && typeof value === 'object'
    ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonicalize(value[key])]))
    : value;
const sha256 = async value => {
  const bytes = new TextEncoder().encode(JSON.stringify(canonicalize(value)));
  const digest = await crypto.subtle.digest('SHA-256', bytes);
  return [...new Uint8Array(digest)].map(byte => byte.toString(16).padStart(2, '0')).join('');
};
const orgId = '<network-log-derived-org-id>';
const envId = '<network-log-derived-env-id>';
const approvedSnapshotDigest = '<approved-snapshot-sha256>';
const approvedBumpLine = '<approved-bump-line>';
if (!/^[A-Za-z0-9_-]{8,128}$/.test(orgId)) throw new Error('invalid orgId');
if (!/^[A-Za-z0-9_-]{8,128}$/.test(envId)) throw new Error('invalid envId');
if (!/^[a-f0-9]{64}$/.test(approvedSnapshotDigest)) throw new Error('invalid approved snapshot digest');
if (!/^# bump \d{4}-\d{2}-\d{2} \d{2}:\d{2}$/.test(approvedBumpLine)) throw new Error('invalid approved bump line');
const endpoint = `https://claude.ai/v1/environment_providers/private/organizations/${encodeURIComponent(orgId)}/environments/${encodeURIComponent(envId)}`;

assertClaudeContext();
const getResp = await fetch(endpoint);
if (!getResp.ok) throw new Error(`GET failed: ${getResp.status}`);
const env = await getResp.json();
if (await sha256(env) !== approvedSnapshotDigest) {
  throw new Error('environment changed after approval');
}
const originalInit = String(env.config.init_script ?? '');
const bumpPattern = /^# bump \d{4}-\d{2}-\d{2} \d{2}:\d{2}(?=\n|$)/;
const stripBump = value => value.replace(/^# bump \d{4}-\d{2}-\d{2} \d{2}:\d{2}(?:\n|$)/, '');
const updatedInit = bumpPattern.test(originalInit)
  ? originalInit.replace(bumpPattern, approvedBumpLine)
  : `${approvedBumpLine}\n${originalInit}`;

if (stripBump(updatedInit) !== stripBump(originalInit)) {
  throw new Error('init_script body changed outside the bump line');
}

const updated = {
  name: env.name,
  description: env.description ?? '',
  config: { ...env.config, init_script: updatedInit }
};
assertClaudeContext();
const resp = await fetch(endpoint, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(updated)
});
if (!resp.ok) throw new Error(`POST failed: ${resp.status}`);

assertClaudeContext();
const verifyResp = await fetch(endpoint);
if (!verifyResp.ok) throw new Error(`verification GET failed: ${verifyResp.status}`);
const after = await verifyResp.json();
const beforeRest = { ...env.config }; delete beforeRest.init_script;
const afterRest = { ...after.config }; delete afterRest.init_script;
if (after.config.init_script !== updatedInit ||
    after.name !== env.name || (after.description ?? '') !== (env.description ?? '') ||
    JSON.stringify(afterRest) !== JSON.stringify(beforeRest)) {
  throw new Error('POST verification mismatch');
}

• GET で現在の init_script を読み取り、会話に控える
• 承認前 call は safe summary と snapshot digest を返す。承認後 call は context guard、endpoint、GET、更新、検証 GET を自己完結させる
• 変更は先頭の日時コメント行 # bump YYYY-MM-DD HH:MM の追加・更新のみ。他の行に触れない。再構築のトリガーは欄のテキストが変わることなので、同日に複数回 bump しても変化が出るよう時刻まで書く
• POST 前に差分を提示して承認を得る
• POST 後は同じ endpoint を GET し、bump 行以外の init_script 本文と他 field が承認前の値から変わっていないことを検証する
• POST が失敗したら手動フォールバック: https://claude.ai/code で下部バーの環境タブ（雲アイコン）→ 歯車アイコン → 「Update cloud environment」ダイアログの Setup script 欄を手で書き換える

init_script が非 0 で終了する状態になると新規セッションが全て起動不能になる。欄を壊さないことを何より優先する。

API レスポンス構造

{
  "environment_id": "env_...",
  "name": "Default",
  "config": {
    "environment_type": "anthropic",
    "sub_type": "ccr",
    "cwd": "/home/user",
    "init_script": "# bump ...\ncurl ...",
    "environment": {},
    "languages": [{ "name": "python", "version": "3.11" }, ...],
    "network_config": { "allowed_hosts": ["*"], "allow_default_hosts": true }
  }
}

UI の「Setup script」は config.init_script、「Environment variables」は config.environment。

POST リクエストの必須フィールド

name, description, config が必要。description は GET に既存値があればそのまま返し、既存の説明文を空文字列で上書きしない。GET に description が無い環境では空文字列で補う。実測では undefined は JSON.stringify で field ごと脱落して 400 (description: Field required)、null も 400、空文字列は成功する。

エンドポイントの再発見

API が変更されて動かなくなった場合の調査手順。

• Claude in Chrome で https://claude.ai/code を開く
• ネットワーク観察が利用できることを確認し、ログをクリアする。利用できなければ手動フォールバック URL を案内して止まる
• 下部バーの環境タブ（雲アイコン）→ 歯車アイコンでダイアログを開く
• ダイアログを開いた時点の GET リクエストの URL からエンドポイントのパス・org_id・env_id が分かる
• ダイアログ表示と GET だけを観察する。Setup script や他の項目は変更せず、「Save changes」をクリックしない
• GET のレスポンスと、既存の frontend bundle 内の request 定義から method、URL、payload のフィールド名を確認する
• 読み取りだけで POST の仕様を特定できなければ、環境を変更せず手動フォールバック URL を案内して止まる。再発見のための試験 POST はユーザー承認前に行わない

反映範囲

再構築が効くのは bump 後に開始した新規セッションだけ。実行中・再開セッションには効かない。