pinglet-cli 0.1.5 → 0.2.0

package/README.md

@@ -41,7 +41,7 @@ codex    # turn 완료 시 macOS 알림으로 Ping 전달 (experimental)
 | `pinglet install [--api <url>] [--force]` | Claude Code / Codex 자동 감지 후 integration 설치 + 서버 등록 + 초기 feed 캐시 |
 | `pinglet uninstall [--purge]` | integration 제거, 기존 설정 복원. `--purge`는 `~/.pinglet`까지 삭제 |
 | `pinglet login [--token <jwt>]` | GitHub 로그인 후 익명 설치를 계정에 연결 |
-| `pinglet post "메시지" [--category <c>]` | 메시지 작성 (설치만 해도 익명 작성 가능, 로그인 시 닉네임 표시) |
+| `pinglet post "메시지" [--category <c>]` | 메시지 작성 (GitHub 로그인 필요, 읽기는 로그인 없이 가능) |
 | `pinglet doctor` | 설치/캐시/큐/서버 상태 진단 |
 | `pinglet ping` | 메시지 미리보기 (이벤트 기록 없음) |
 
@@ -64,10 +64,12 @@ install 시 `~/.claude/commands/pinglet.md` slash command가 함께 설치되며
   `node <cli> statusline`을 연결한다. statusline은 UI 영역이라 LLM context에
   전혀 들어가지 않으며(Zero Token), Thinking/Working 중에 메시지가 보인다.
   기존 statusLine 설정은 백업 후 uninstall 시 복원한다.
-  - **Spinner verbs** — `refresh` 배치가 feed를 받을 때 `spinnerVerbs`(mode:
-    "replace")에도 메시지를 등록해, "Befuddling…" 같은 기본 verb 자리에 Ping이
-    그대로 표시된다. Pinglet이 쓴 verb는 zero-width space 마커로 식별하므로
-    사용자가 직접 등록한 verb는 건드리지 않고, uninstall 시 원래대로 복원한다.
+  - **Spinner verbs (pool=1 회전)** — `spinnerVerbs`(mode: "replace")에 메시지를
+    **한 번에 하나만** 등록해 "Befuddling…" 자리에 Ping이 표시된다. statusline이
+    60초마다 다음 메시지로 교체하며, Claude Code가 설정을 핫리로드하므로 세션
+    중에도 즉시 반영된다. pool이 1개라 "spinner가 돌았다 = 이 메시지가 표시됐다"가
+    확정된다. Pinglet verb는 zero-width space 마커로 식별하므로 사용자가 직접
+    등록한 verb는 건드리지 않고, uninstall 시 원래대로 복원한다.
 - **Codex Adapter (experimental)** — `~/.codex/config.toml`의 `notify` hook에 연결.
   notify는 TUI 밖 프로세스라 터미널 안에 그릴 수 없어, MVP에서는 turn 완료 시
   macOS 알림으로 전달한다.
@@ -79,9 +81,11 @@ install 시 `~/.claude/commands/pinglet.md` slash command가 함께 설치되며
   네트워크가 절대 들어가지 않는다.
 - **오프라인 동작** — 서버 미연결 시 시드 메시지로 동작하고, 등록/feed 갱신은
   백그라운드 `refresh`가 온라인이 되면 자동 재시도한다.
-- **DELIVERED / QUALIFIED_IMPRESSION 분리** — 메시지 표시 시 DELIVERED를 기록하고,
-  30초 회전 주기에 3초 이상 유지된 메시지만 QUALIFIED_IMPRESSION(visibleMs 포함)으로
-  정산한다. 세션이 끊긴 구간은 마지막 tick까지만 노출로 계산한다.
+- **DELIVERED / QUALIFIED_IMPRESSION 분리** — 메시지가 spinner에 armed되면
+  DELIVERED(설치당 1회), armed된 동안 spinner가 3초 이상 실제로 돌았으면
+  QUALIFIED_IMPRESSION(visibleMs 포함)으로 정산한다. "실제로 돌았는지"는
+  statusline hook이 받는 `cost.total_api_duration_ms` 증가분으로 측정한다 —
+  pool이 1개이므로 API 활동 시간만큼 그 메시지가 표시된 것이 확정된다.
 - **Async Telemetry** — 이벤트는 `~/.pinglet/events.jsonl`(Local Event Queue)에
   append하고, 20개 이상 또는 60초 주기로 detached 프로세스가 batch 전송한다.
   전송 성공분만 큐에서 제거하므로 실패분은 자동 재시도되며, 재전송 중복은

package/dist/adapters/claude.js

@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectClaude = detectClaude;
-exports.syncSpinnerVerbs = syncSpinnerVerbs;
+exports.armSpinnerMessage = armSpinnerMessage;
 exports.spinnerVerbsStatus = spinnerVerbsStatus;
 exports.isClaudeIntegrationInstalled = isClaudeIntegrationInstalled;
 exports.installClaudeIntegration = installClaudeIntegration;
@@ -131,19 +131,42 @@ const MAX_VERBS = 30;
 /** spinner 한 줄에 "(27s · ↓ 1.0k tokens)" 등이 뒤에 붙으므로 여유를 둔다. */
 const MAX_VERB_LEN = 60;
 function readSettings() {
+    return readSettingsWithMtime().settings;
+}
+function settingsMtimeMs() {
+    try {
+        return fs.statSync(SETTINGS_PATH).mtimeMs;
+    }
+    catch {
+        return null; // 파일 없음
+    }
+}
+function readSettingsWithMtime() {
+    const mtimeMs = settingsMtimeMs();
     try {
-        return JSON.parse(fs.readFileSync(SETTINGS_PATH, "utf8"));
+        return {
+            settings: JSON.parse(fs.readFileSync(SETTINGS_PATH, "utf8")),
+            mtimeMs,
+        };
     }
     catch {
-        return {};
+        return { settings: {}, mtimeMs };
     }
 }
-function writeSettings(settings) {
+/**
+ * mtime이 읽던 시점 그대로일 때만 쓴다 — 변경이 감지되면 false를 돌려주고
+ * 호출부가 다시 읽어 재적용한다. Claude Code 자신도 이 파일을 쓰기 때문에,
+ * 그 사이의 변경을 우리 스냅샷으로 덮어써 사용자 설정을 유실하면 안 된다.
+ */
+function writeSettings(settings, expectedMtimeMs) {
     fs.mkdirSync(CLAUDE_DIR, { recursive: true });
+    if (settingsMtimeMs() !== expectedMtimeMs)
+        return false;
     // settings.json은 Claude Code가 수시로 읽는 파일이라 tmp+rename으로 원자적으로 쓴다.
     const tmp = SETTINGS_PATH + ".pinglet-tmp";
     fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n");
     fs.renameSync(tmp, SETTINGS_PATH);
+    return true;
 }
 function isPingletTip(tip) {
     return tip.startsWith(PINGLET_TIP_MARKER);
@@ -184,52 +207,68 @@ function cleanupSpinnerTips(settings, config) {
     return true;
 }
 /**
- * Claude Code spinner verb("Befuddling…" 자리)를 feed 메시지로 교체한다.
- * mode: "replace"라 기본 verb 대신 Ping이 그대로 spinner 본문에 표시된다.
+ * Claude Code spinner verb("Befuddling…" 자리)에 메시지 **하나만** armed한다.
+ * pool을 1개로 유지해야 "spinner가 돌았다 = 이 메시지가 표시됐다"가 확정되고,
+ * cost 델타 기반 노출 측정(statusline)이 정확해진다. 설정은 핫리로드된다.
+ * message가 null이면 우리 verb를 걷어내고 기본 spinner로 되돌린다.
  * 마커가 붙은 항목만 Pinglet 소유로 보고 교체하며, 사용자 verb는 유지한다.
  */
-function syncSpinnerVerbs(config, messages) {
+function armSpinnerMessage(config, message) {
     const adapter = config.adapters.claude;
     if (!adapter)
         return false;
-    const settings = readSettings();
-    cleanupSpinnerTips(settings, config);
-    const existing = settings.spinnerVerbs;
-    const existingVerbs = existing?.verbs ?? [];
-    // 사용자가 원래 갖고 있던 spinnerVerbs는 최초 1회 백업해 두고 uninstall 시 복원한다.
-    const isOurs = existingVerbs.some(isPingletTip);
-    if (existing && !isOurs && adapter.spinnerVerbsBackup === undefined) {
-        adapter.spinnerVerbsBackup = existing;
-        (0, config_1.saveConfig)(config);
-    }
-    const userVerbs = existingVerbs.filter((verb) => !isPingletTip(verb));
-    const pingletVerbs = buildPingletVerbs(messages);
-    // 실제 feed 메시지가 없으면 spinner를 교체하지 않는다 —
-    // 우리가 넣어둔 verb가 있으면 걷어내고 Claude Code 기본 spinner로 되돌린다.
-    if (pingletVerbs.length === 0) {
-        if (!isOurs)
-            return false;
-        const backup = adapter.spinnerVerbsBackup;
-        if (backup) {
-            settings.spinnerVerbs = backup;
-            delete adapter.spinnerVerbsBackup;
+    // 읽기~쓰기 사이에 다른 프로세스(Claude Code 등)가 파일을 바꿨으면
+    // writeSettings가 거부하므로, 다시 읽어 재적용한다.
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const { settings, mtimeMs } = readSettingsWithMtime();
+        cleanupSpinnerTips(settings, config);
+        const existing = settings.spinnerVerbs;
+        const existingVerbs = existing?.verbs ?? [];
+        // 사용자가 원래 갖고 있던 spinnerVerbs는 최초 1회 백업해 두고 uninstall 시 복원한다.
+        const isOurs = existingVerbs.some(isPingletTip);
+        if (existing && !isOurs && adapter.spinnerVerbsBackup === undefined) {
+            adapter.spinnerVerbsBackup = existing;
             (0, config_1.saveConfig)(config);
         }
-        else if (userVerbs.length > 0) {
-            settings.spinnerVerbs = { ...existing, verbs: userVerbs };
+        const userVerbs = existingVerbs.filter((verb) => !isPingletTip(verb));
+        const pingletVerbs = message ? buildPingletVerbs([message]) : [];
+        // armed할 메시지가 없으면 spinner를 기본 상태로 되돌린다.
+        if (pingletVerbs.length === 0) {
+            if (!isOurs)
+                return false;
+            const backup = adapter.spinnerVerbsBackup;
+            if (backup) {
+                settings.spinnerVerbs = backup;
+            }
+            else if (userVerbs.length > 0) {
+                settings.spinnerVerbs = { ...existing, verbs: userVerbs };
+            }
+            else {
+                delete settings.spinnerVerbs;
+            }
+            if (writeSettings(settings, mtimeMs)) {
+                // 쓰기가 확정된 뒤에만 백업을 소비한다 (실패 시 백업 유실 방지).
+                if (backup) {
+                    delete adapter.spinnerVerbsBackup;
+                    (0, config_1.saveConfig)(config);
+                }
+                return false;
+            }
+            continue;
         }
-        else {
-            delete settings.spinnerVerbs;
+        const next = [...userVerbs, ...pingletVerbs];
+        // 같은 메시지를 다시 armed하는 경우 파일 쓰기를 생략한다 (300ms 렌더링 경로 보호).
+        if (existing?.mode === "replace" &&
+            existingVerbs.length === next.length &&
+            existingVerbs.every((v, i) => v === next[i])) {
+            return true;
         }
-        writeSettings(settings);
-        return false;
+        settings.spinnerVerbs = { mode: "replace", verbs: next };
+        if (writeSettings(settings, mtimeMs))
+            return true;
     }
-    settings.spinnerVerbs = {
-        mode: "replace",
-        verbs: [...userVerbs, ...pingletVerbs],
-    };
-    writeSettings(settings);
-    return true;
+    // 계속 충돌하면 이번 tick은 건너뛴다 — 다음 statusline tick에서 재시도된다.
+    return false;
 }
 /** doctor용: spinner verb로 등록된 Pinglet 메시지 개수. */
 function spinnerVerbsStatus() {
@@ -242,75 +281,84 @@ function isClaudeIntegrationInstalled() {
     return settings.statusLine?.command?.includes("pinglet") ?? false;
 }
 function installClaudeIntegration(config, options = {}) {
-    const settings = readSettings();
-    const existing = settings.statusLine;
-    const isOurs = existing?.command?.includes("pinglet");
-    if (existing && !isOurs && !options.force) {
-        return {
-            ok: false,
-            reason: "기존 statusLine 설정이 있습니다. 덮어쓰려면 --force로 다시 실행하세요.",
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const { settings, mtimeMs } = readSettingsWithMtime();
+        const existing = settings.statusLine;
+        const isOurs = existing?.command?.includes("pinglet");
+        if (existing && !isOurs && !options.force) {
+            return {
+                ok: false,
+                reason: "기존 statusLine 설정이 있습니다. 덮어쓰려면 --force로 다시 실행하세요.",
+            };
+        }
+        config.adapters.claude = {
+            // 재설치 시 기존 백업(spinnerVerbsBackup 등)이 날아가지 않게 유지한다.
+            ...config.adapters.claude,
+            installedAt: new Date().toISOString(),
+            settingsPath: SETTINGS_PATH,
+            // 사용자의 기존 설정은 백업해 두고 uninstall 시 복원한다.
+            ...(existing && !isOurs && { statusLineBackup: existing }),
         };
+        (0, config_1.saveConfig)(config);
+        settings.statusLine = { type: "command", command: statusLineCommand() };
+        uninstallPromptHook(settings); // 구버전 hook 방식 흔적 정리
+        if (!writeSettings(settings, mtimeMs))
+            continue; // 다른 프로세스와 충돌 → 재읽기
+        installSlashCommand();
+        // spinner verb는 로컬 캐시에 실제 feed가 있을 때만 채운다. 없으면 기본 spinner 유지.
+        armSpinnerMessage(config, (0, cache_1.loadFeedMessages)()[0] ?? null);
+        return { ok: true };
     }
-    config.adapters.claude = {
-        // 재설치 시 기존 백업(spinnerVerbsBackup 등)이 날아가지 않게 유지한다.
-        ...config.adapters.claude,
-        installedAt: new Date().toISOString(),
-        settingsPath: SETTINGS_PATH,
-        // 사용자의 기존 설정은 백업해 두고 uninstall 시 복원한다.
-        ...(existing && !isOurs && { statusLineBackup: existing }),
+    return {
+        ok: false,
+        reason: "settings.json이 계속 변경되고 있어 설치하지 못했습니다. 잠시 후 다시 시도하세요.",
     };
-    (0, config_1.saveConfig)(config);
-    settings.statusLine = { type: "command", command: statusLineCommand() };
-    uninstallPromptHook(settings); // 구버전 hook 방식 흔적 정리
-    writeSettings(settings);
-    installSlashCommand();
-    // spinner verb는 로컬 캐시에 실제 feed가 있을 때만 채운다. 없으면 기본 spinner 유지.
-    syncSpinnerVerbs(config, (0, cache_1.loadFeedMessages)());
-    return { ok: true };
 }
 function uninstallClaudeIntegration(config) {
-    const settings = readSettings();
-    let changed = false;
-    if (settings.statusLine?.command?.includes("pinglet")) {
-        const backup = config.adapters.claude?.statusLineBackup;
-        if (backup) {
-            settings.statusLine = backup;
+    let settingsChanged = false;
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const { settings, mtimeMs } = readSettingsWithMtime();
+        settingsChanged = false;
+        if (settings.statusLine?.command?.includes("pinglet")) {
+            const backup = config.adapters.claude?.statusLineBackup;
+            if (backup) {
+                settings.statusLine = backup;
+            }
+            else {
+                delete settings.statusLine;
+            }
+            settingsChanged = true;
         }
-        else {
-            delete settings.statusLine;
+        if (cleanupSpinnerTips(settings, config)) {
+            settingsChanged = true;
         }
-        changed = true;
-    }
-    if (cleanupSpinnerTips(settings, config)) {
-        changed = true;
-    }
-    if (uninstallPromptHook(settings)) {
-        changed = true;
-    }
-    if (uninstallSlashCommand()) {
-        changed = true;
-    }
-    const verbs = settings.spinnerVerbs;
-    if (verbs?.verbs?.some(isPingletTip)) {
-        const verbsBackup = config.adapters.claude?.spinnerVerbsBackup;
-        const userVerbs = verbs.verbs.filter((verb) => !isPingletTip(verb));
-        if (verbsBackup) {
-            settings.spinnerVerbs = verbsBackup;
-        }
-        else if (userVerbs.length > 0) {
-            settings.spinnerVerbs = { ...verbs, verbs: userVerbs };
+        if (uninstallPromptHook(settings)) {
+            settingsChanged = true;
         }
-        else {
-            delete settings.spinnerVerbs;
+        const verbs = settings.spinnerVerbs;
+        if (verbs?.verbs?.some(isPingletTip)) {
+            const verbsBackup = config.adapters.claude?.spinnerVerbsBackup;
+            const userVerbs = verbs.verbs.filter((verb) => !isPingletTip(verb));
+            if (verbsBackup) {
+                settings.spinnerVerbs = verbsBackup;
+            }
+            else if (userVerbs.length > 0) {
+                settings.spinnerVerbs = { ...verbs, verbs: userVerbs };
+            }
+            else {
+                delete settings.spinnerVerbs;
+            }
+            settingsChanged = true;
         }
-        changed = true;
-    }
-    if (changed) {
-        writeSettings(settings);
+        if (!settingsChanged)
+            break;
+        if (writeSettings(settings, mtimeMs))
+            break; // 충돌 시 재읽기 후 재적용
     }
+    const commandRemoved = uninstallSlashCommand();
     if (config.adapters.claude) {
         delete config.adapters.claude;
         (0, config_1.saveConfig)(config);
     }
-    return changed;
+    return settingsChanged || commandRemoved;
 }

package/dist/api.js

@@ -140,12 +140,12 @@ async function fetchMessageStats(config, messageId) {
 }
 /**
  * POST /messages — 메시지 작성 (분당 5개 제한).
- * 로그인했으면 유저 토큰으로(닉네임 표시), 아니면 설치 토큰으로 익명 작성한다.
+ * 작성은 GitHub 로그인이 필요하다 (읽기는 계속 익명).
  */
 async function createMessage(config, text, category) {
-    const token = config.userToken ?? Object.values(config.installations)[0]?.token;
+    const token = config.userToken;
     if (!token)
-        return { ok: false, error: "UNAUTHORIZED" };
+        return { ok: false, error: "LOGIN_REQUIRED" };
     try {
         const res = await fetch(config.apiBaseUrl + "/messages", {
             method: "POST",
@@ -174,10 +174,13 @@ async function createMessage(config, text, category) {
         return { ok: false, error: "NETWORK" };
     }
 }
-/** POST /installations/link — 로그인 후 기존 익명 설치를 계정에 연결한다. */
-async function linkInstallation(config, installationId) {
+/**
+ * POST /installations/link — 로그인 후 기존 익명 설치를 계정에 연결한다.
+ * 소유 증명으로 installation "토큰"을 보낸다 (ID만으로는 연결 불가).
+ */
+async function linkInstallation(config, installationToken) {
     if (!config.userToken)
         return false;
-    const res = await request(config, "POST", "/installations/link", { token: config.userToken, body: { installationId } });
+    const res = await request(config, "POST", "/installations/link", { token: config.userToken, body: { installationToken } });
     return res?.linked === true;
 }

package/dist/cli.js

@@ -19,8 +19,8 @@ const HELP = `pinglet v${config_1.VERSION} — AI가 생각하는 동안 만나
   install [--api <url>] [--force]   Claude Code / Codex 자동 감지 후 integration 설치
           [--claude | --codex]      특정 agent만 설치
   uninstall [--purge]               integration 제거 (--purge: ~/.pinglet까지 삭제)
-  login [--token <jwt>]             GitHub 계정 연결 (선택)
-  post "메시지" [--category <c>]     메시지 작성 (설치만 해도 익명 작성 가능)
+  login [--token <jwt>]             GitHub 계정 연결
+  post "메시지" [--category <c>]     메시지 작성 (GitHub 로그인 필요, 읽기는 익명 가능)
   doctor                            설치/캐시/서버 상태 진단
   ping                              메시지 미리보기
 

package/dist/commands/doctor.js

@@ -81,6 +81,6 @@ async function runDoctor() {
     if (config.userToken)
         ok("로그인됨");
     else
-        warn("로그인 안 됨 — 익명 작성은 가능, 닉네임 표시/반응은 `pinglet login` 후");
+        warn("로그인 안 됨 — 읽기는 가능, 메시지 작성/반응은 `pinglet login` 후");
     console.log("");
 }

package/dist/commands/install.js

@@ -65,7 +65,7 @@ async function runInstall(args) {
             (0, cache_1.saveFeedMessages)(messages);
             if (messages.length > 0) {
                 console.log(`✓ Feed cached (${messages.length} messages)`);
-                if ((0, claude_1.syncSpinnerVerbs)(config, messages)) {
+                if ((0, claude_1.armSpinnerMessage)(config, messages[0] ?? null)) {
                     console.log("✓ Claude spinner synced");
                 }
             }
@@ -73,6 +73,6 @@ async function runInstall(args) {
     }
     console.log("\n설치 완료! 평소처럼 claude 또는 codex를 실행하면 Ping이 표시됩니다.");
     console.log("  상태 확인:   pinglet doctor");
-    console.log('  메시지 작성: pinglet post "메시지"  (익명 — 바로 가능)');
-    console.log("  계정 연결:   pinglet login  (선택 — 닉네임 표시/반응에 필요)");
+    console.log('  메시지 작성: pinglet login 후 pinglet post "메시지"');
+    console.log("  계정 연결:   pinglet login  (메시지 작성/반응에 필요)");
 }

package/dist/commands/login.js

@@ -82,7 +82,7 @@ async function runLogin(args) {
     (0, config_1.saveConfig)(config);
     console.log("✓ 로그인 정보 저장 완료");
     for (const [agentType, record] of Object.entries(config.installations)) {
-        const linked = await (0, api_1.linkInstallation)(config, record.installationId);
+        const linked = await (0, api_1.linkInstallation)(config, record.token);
         console.log(linked
             ? `✓ ${agentType} installation을 계정에 연결했습니다`
             : `○ ${agentType} installation 연결 실패 — 서버 연결 후 다시 시도하세요`);

package/dist/commands/post.js

@@ -10,6 +10,7 @@ const REASON_LABELS = {
     URL_NOT_ALLOWED: "URL은 허용되지 않습니다",
     PII_DETECTED: "이메일/전화번호 등 개인정보가 포함되어 있습니다",
     BANNED_WORD: "정책상 검토가 필요한 표현이 포함되어 있습니다",
+    CONTROL_CHARS: "제어 문자(escape sequence)는 허용되지 않습니다",
 };
 /**
  * `pinglet post "메시지" [--category <카테고리>] [--quiet]`
@@ -40,8 +41,11 @@ async function runPost(args) {
     const result = await (0, api_1.createMessage)(config, text, category);
     if (!result.ok) {
         switch (result.error) {
+            case "LOGIN_REQUIRED":
+                console.log("✗ 메시지 작성에는 GitHub 로그인이 필요합니다. `pinglet login`을 실행하세요 (읽기는 로그인 없이 가능).");
+                break;
             case "UNAUTHORIZED":
-                console.log("✗ 인증 정보가 없습니다. 먼저 `pinglet install`을 실행하세요 (로그인 없이도 익명 작성 가능).");
+                console.log("✗ 로그인이 만료됐습니다. `pinglet login`으로 다시 로그인하세요.");
                 break;
             case "RATE_LIMITED":
                 console.log("✗ 작성 제한(분당 5개)에 걸렸습니다. 잠시 후 다시 시도하세요.");
@@ -67,9 +71,6 @@ async function runPost(args) {
             console.log("✓ 메시지가 등록됐습니다. 곧 다른 개발자들의 터미널에 표시됩니다.");
             if (!quiet) {
                 console.log(`  id: ${result.id}`);
-                if (!config.userToken) {
-                    console.log("  '익명의 개발자'로 표시됩니다 — 닉네임을 달려면 `pinglet login`");
-                }
             }
             break;
         case "PENDING_REVIEW":

package/dist/commands/refresh.js

@@ -4,7 +4,6 @@ exports.runRefresh = runRefresh;
 const config_1 = require("../config");
 const api_1 = require("../api");
 const cache_1 = require("../cache");
-const queue_1 = require("../queue");
 const claude_1 = require("../adapters/claude");
 /**
  * 서버 feed를 미리 받아 Local Feed Cache를 갱신한다 (아키텍처 §6).
@@ -33,24 +32,14 @@ async function runRefresh() {
     const messages = await (0, api_1.fetchFeed)(config, records[0]);
     if (messages) {
         (0, cache_1.saveFeedMessages)(messages);
-        // 새 feed를 Claude Code spinner verb에도 반영한다 (설정 파일만 다시 쓰면 됨).
-        // feed가 비었으면 spinner를 기본 상태로 되돌린다.
-        (0, claude_1.syncSpinnerVerbs)(config, messages);
-        // spinner는 실제 노출 시점을 알 수 없으므로, spinner pool에 실린 시점을
-        // "전달(DELIVERED)"로 기록한다. 메시지당 설치 1회만.
-        if (config.adapters.claude && config.installations.CLAUDE) {
-            const state = (0, cache_1.loadState)();
-            state.delivered ??= {};
-            let changed = false;
-            for (const m of messages) {
-                if (state.delivered[m.id])
-                    continue;
-                (0, queue_1.appendEvent)({ agentType: "CLAUDE", type: "DELIVERED", messageId: m.id });
-                state.delivered[m.id] = 1;
-                changed = true;
-            }
-            if (changed)
-                (0, cache_1.saveState)(state);
+        // spinner 회전과 DELIVERED/QUALIFIED 기록은 statusline이 담당한다 (pool=1).
+        // 여기서는 armed된 메시지가 서버에서 사라진 경우만 즉시 정리한다.
+        const state = (0, cache_1.loadState)();
+        const current = state.current;
+        if (current && !messages.some((m) => m.id === current.messageId)) {
+            (0, claude_1.armSpinnerMessage)(config, messages[0] ?? null);
+            state.current = undefined; // 다음 statusline tick이 정식으로 다음 메시지를 armed한다
+            (0, cache_1.saveState)(state);
         }
     }
     // 이 기기에서 작성한 최근 메시지의 도달 통계를 갱신한다 (statusline 표시용).

package/dist/commands/statusline.js

@@ -1,20 +1,136 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runStatusline = runStatusline;
+const fs = __importStar(require("fs"));
+const config_1 = require("../config");
 const cache_1 = require("../cache");
 const render_1 = require("../render");
+const picker_1 = require("../picker");
+const queue_1 = require("../queue");
+const claude_1 = require("../adapters/claude");
 const runtime_1 = require("../runtime");
+function readPayload() {
+    try {
+        return JSON.parse(fs.readFileSync(0, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * cost.total_api_duration_ms 증가분 = 이 tick 사이에 spinner가 실제로 돈 시간.
+ * spinner pool이 1개이므로 그 시간만큼 armed 메시지가 화면에 표시된 것이 확정된다.
+ */
+function trackSpinnerActivity(state, payload) {
+    const sessionId = payload.session_id;
+    const apiMs = payload.cost?.total_api_duration_ms;
+    if (!sessionId || typeof apiMs !== "number")
+        return;
+    state.sessions ??= {};
+    const prev = state.sessions[sessionId];
+    state.sessions[sessionId] = apiMs;
+    // 오래된 세션 기록이 무한히 쌓이지 않게 상한을 둔다.
+    const ids = Object.keys(state.sessions);
+    if (ids.length > 20)
+        delete state.sessions[ids[0]];
+    if (prev === undefined || apiMs <= prev || !state.current)
+        return;
+    state.current.visibleMs = Math.min((state.current.visibleMs ?? 0) + (apiMs - prev), runtime_1.ROTATE_MS);
+}
+/**
+ * 이전 armed 메시지의 노출을 정산하고 다음 메시지를 armed한다.
+ * QUALIFIED_MS 이상 spinner가 돌았으면 유효 노출(visibleMs 포함)로 기록한다.
+ */
+function rotateSpinner(state, now) {
+    const config = (0, config_1.loadConfig)();
+    const prev = state.current;
+    if (prev && (prev.visibleMs ?? 0) >= runtime_1.QUALIFIED_MS) {
+        (0, queue_1.appendEvent)({
+            agentType: "CLAUDE",
+            type: "QUALIFIED_IMPRESSION",
+            messageId: prev.messageId,
+            visibleMs: prev.visibleMs,
+        });
+    }
+    const message = (0, picker_1.pickMessage)((0, cache_1.loadFeedMessages)(), state);
+    if (!message) {
+        (0, claude_1.armSpinnerMessage)(config, null);
+        state.current = undefined;
+        return;
+    }
+    (0, claude_1.armSpinnerMessage)(config, message);
+    state.seen[message.id] = (state.seen[message.id] ?? 0) + 1;
+    state.delivered ??= {};
+    if (!state.delivered[message.id]) {
+        (0, queue_1.appendEvent)({
+            agentType: "CLAUDE",
+            type: "DELIVERED",
+            messageId: message.id,
+        });
+        state.delivered[message.id] = 1;
+    }
+    state.current = {
+        messageId: message.id,
+        text: message.text,
+        author: message.author,
+        shownAt: now,
+        visibleMs: 0,
+    };
+}
 /**
  * Claude Code statusLine hook 진입점.
- * Ping 메시지는 spinner(spinnerVerbs)가 담당하고, statusline에는
- * 이 기기에서 작성한 최근 메시지의 도달 현황을 보여준다.
- * flush/refresh 백그라운드 트리거도 이 경로에서 돈다 (Claude 사용 중 항상 호출되므로).
+ * - spinner 회전(pool=1): ROTATE_MS마다 다음 메시지를 armed (설정 핫리로드로 즉시 반영)
+ * - 노출 측정: stdin payload의 cost 델타로 armed 메시지의 실제 표시 시간을 누적
+ * - statusline 표시: 이 기기에서 작성한 최근 메시지의 도달 현황
+ * - flush/refresh 백그라운드 트리거 (Claude 사용 중 항상 호출되므로 이 경로에서)
  */
 function runStatusline() {
+    const payload = readPayload();
     const state = (0, cache_1.loadState)();
     const now = Date.now();
-    // 300ms마다 호출되므로 상태 기록/maintenance는 1초 스로틀.
-    if (state.lastTickAt === undefined || now - state.lastTickAt > 1_000) {
+    trackSpinnerActivity(state, payload);
+    const rotateDue = !state.current || now - state.current.shownAt >= runtime_1.ROTATE_MS;
+    // 300ms마다 호출되므로 저장/maintenance는 1초 스로틀. 회전 시점에는 항상 저장.
+    const saveDue = rotateDue ||
+        state.lastTickAt === undefined ||
+        now - state.lastTickAt > 1_000;
+    if (rotateDue) {
+        rotateSpinner(state, now);
+    }
+    if (saveDue) {
         (0, runtime_1.runMaintenance)(state, now);
         state.lastTickAt = now;
         (0, cache_1.saveState)(state);

package/dist/render.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.supportsUnicode = supportsUnicode;
+exports.sanitizeForTerminal = sanitizeForTerminal;
 exports.formatPing = formatPing;
 exports.formatMyReach = formatMyReach;
 /** 터미널 독립 원칙: unicode가 불확실하면 plain ASCII로 fallback (아키텍처 §5). */
@@ -10,18 +11,30 @@ function supportsUnicode() {
     const locale = process.env.LC_ALL || process.env.LC_CTYPE || process.env.LANG || "";
     return /utf-?8/i.test(locale);
 }
+/**
+ * 터미널에 그리기 전 최종 방어선: 제어·서식 문자를 제거한다.
+ * 서버 moderation이 이미 거르지만, 구버전 서버·손상된 캐시를 신뢰하지 않는다
+ * (ANSI escape가 살아 있으면 수신자 터미널을 조작할 수 있다).
+ */
+function sanitizeForTerminal(text) {
+    return text
+        .replace(/\s+/g, " ")
+        .replace(/[\p{Cc}\p{Cf}]/gu, "")
+        .trim();
+}
 /** 작성자 닉네임 없이 메시지만 표시한다 (spinner verb용). */
 function formatPing(message) {
     const sponsored = message.contentType === "SPONSORED" ? "[AD] " : "";
+    const text = sanitizeForTerminal(message.text);
     if (supportsUnicode()) {
-        return `💌 ${sponsored}"${message.text}"`;
+        return `💌 ${sponsored}"${text}"`;
     }
-    return `[ping] ${sponsored}"${message.text}"`;
+    return `[ping] ${sponsored}"${text}"`;
 }
 const REACH_TEXT_MAX = 24;
 /** statusline용: 내가 쓴 최근 메시지의 도달 현황 한 줄 (커버리지 = 도달/활성 설치). */
 function formatMyReach(stats) {
-    let text = stats.text;
+    let text = sanitizeForTerminal(stats.text);
     if (text.length > REACH_TEXT_MAX)
         text = text.slice(0, REACH_TEXT_MAX - 1) + "…";
     const reached = stats.reachedInstallations;

package/dist/runtime.js

@@ -1,11 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FEED_TTL_MS = exports.FLUSH_COUNT = exports.FLUSH_INTERVAL_MS = void 0;
+exports.FEED_TTL_MS = exports.FLUSH_COUNT = exports.FLUSH_INTERVAL_MS = exports.QUALIFIED_MS = exports.ROTATE_MS = void 0;
 exports.runMaintenance = runMaintenance;
 const child_process_1 = require("child_process");
 const config_1 = require("./config");
 const cache_1 = require("./cache");
 const queue_1 = require("./queue");
+exports.ROTATE_MS = 60_000; // spinner 메시지 교체 주기 (설정 핫리로드로 즉시 반영)
+exports.QUALIFIED_MS = 3_000; // 유효 노출로 인정하는 최소 spinner 가동 시간
 exports.FLUSH_INTERVAL_MS = 60_000; // batch 전송 주기
 exports.FLUSH_COUNT = 20; // 또는 이벤트 개수 기준
 exports.FEED_TTL_MS = 5 * 60_000; // feed 캐시 갱신 주기

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pinglet-cli",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "AI가 생각하는 동안 다른 개발자의 Ping을 만나는 메시지 네트워크 — Claude Code / Codex integration",
   "license": "MIT",
   "repository": {