@michelj/context-guard 0.6.4 → 0.6.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@michelj/context-guard",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "description": "Next-generation collaboration layer for humans and coding agents on Codex, Cursor, and Claude.",
   "repository": {
     "type": "git",
@@ -56,8 +56,8 @@
     "node": ">=18"
   },
   "devDependencies": {
-    "@michelj/context-guard-core": "https://github.com/Michel-Johnson/Context-Guard-Cloud/releases/download/shared-v1.1.2/michelj-context-guard-core-1.1.2.tgz",
-    "@michelj/context-guard-workbench": "https://github.com/Michel-Johnson/Context-Guard-Cloud/releases/download/shared-v1.1.2/michelj-context-guard-workbench-1.1.2.tgz",
+    "@michelj/context-guard-core": "https://github.com/Michel-Johnson/Context-Guard-Cloud/releases/download/shared-v1.1.4/michelj-context-guard-core-1.1.4.tgz",
+    "@michelj/context-guard-workbench": "https://github.com/Michel-Johnson/Context-Guard-Cloud/releases/download/shared-v1.1.4/michelj-context-guard-workbench-1.1.4.tgz",
     "marked": "15.0.12",
     "playwright": "1.62.1"
   }

package/prototype/workbench-app.js

@@ -63,6 +63,12 @@ const I18N = {
     workCopy1:"浏览器在按写死的步骤和稿子走，没有模型在读 OpenClaw 或本仓库。真实 skill 启用时，才由你正在对话的那个 Agent 读代码。",
     workCopy2:"下面的笔记是预置演示稿。真做时先商量第一层怎么切，定了再往下拆；卡名必须一眼能看懂。演示里第一页仍是定稿后的 4–8 张主干。这不是这次点击实时读仓得到的。",
     trayTitle:"已取消的提议",
+    trayClose:"关闭已取消的提议",
+    deviceApprovals:"设备连接申请", deviceApprovalsClose:"关闭设备连接申请", deviceApprovalsRefresh:"刷新申请",
+    deviceApprovalScope:"仅允许你发起的连接：读取本项目 Main、读写自身 Session；不授予管理或 Main 发布权限。",
+    deviceApprovalsEmpty:"没有待审批申请。", deviceAllow:"允许连接", deviceDeny:"拒绝", devicePending:"待审批", deviceOld:"旧申请",
+    deviceApprovalsFailed:"申请读取失败，请重新登录或刷新。", deviceDecisionUnknown:"决定尚未确认，请刷新核对。", deviceDecisionDone:"申请已处理。",
+    deviceLoginRequired:"登录已失效，请重新登录。", deviceTicketRefresh:"审批表单已失效，请刷新申请重试。", deviceAccessRevoked:"仓库授权已撤销，无法审批。", deviceScopeUnavailable:"该项目申请不可用，请刷新核对。", deviceAlreadyDecided:"申请已处理，请刷新核对。",
     trayHint:"已隐藏，后续 Agent 不会读到。可重新加入 Context Map，或永久删除。",
     openBugs:"Bug 处理状态", openTodos:"TODO 处理状态",
     boot_ready:"已建图", boot_proposed:"待确认", boot_analyzing:"分析中", boot_pending:"首次使用",
@@ -167,6 +173,12 @@ const I18N = {
     workCopy1:"The browser is walking hard-coded steps. No model is reading OpenClaw or this repo. When the real skill runs, the agent you are talking to reads the code.",
     workCopy2:"The notes below are a prepared demo. Real first-use decides L1 with you, then goes deeper; titles must be instantly readable. This demo still shows the agreed 4–8 trunk cards. This is not a live read of the repo.",
     trayTitle:"Cancelled proposals",
+    trayClose:"Close cancelled proposals",
+    deviceApprovals:"Device connection requests", deviceApprovalsClose:"Close device connection requests", deviceApprovalsRefresh:"Refresh requests",
+    deviceApprovalScope:"Allow only connections you initiated: read this project's Main and read/write your own Sessions; no administration or Main publication permission.",
+    deviceApprovalsEmpty:"No pending requests.", deviceAllow:"Allow connection", deviceDeny:"Deny", devicePending:"Pending", deviceOld:"Older request",
+    deviceApprovalsFailed:"Requests unavailable. Sign in or refresh.", deviceDecisionUnknown:"Decision not confirmed. Refresh to check.", deviceDecisionDone:"Request processed.",
+    deviceLoginRequired:"Sign-in expired. Sign in again.", deviceTicketRefresh:"Approval form expired. Refresh the request.", deviceAccessRevoked:"Repository authorization was revoked.", deviceScopeUnavailable:"Project request unavailable. Refresh to check.", deviceAlreadyDecided:"Request already processed. Refresh to check.",
     trayHint:"Hidden. Later agents will not read these. Restore them to the map, or delete permanently.",
     openBugs:"Bug status", openTodos:"TODO status",
     boot_ready:"Mapped", boot_proposed:"Pending", boot_analyzing:"Analyzing", boot_pending:"First use",
@@ -979,6 +991,7 @@ function syncBootstrapFromTree(){
   }
 }
 let workbenchSync = null;
+let refreshDeviceApprovals = null;
 let applyingServerMap = false;
 let renderedAccessSession = null;
 let hasRenderedAccessSession = false;
@@ -2414,7 +2427,7 @@ function exitBugPath(restore){
 }
 function openBugPanel(open, kind=activeWorkPanelKind){
   if(open){
-    document.getElementById("tray").classList.remove("open");
+    closeTray();
     const coordinator=document.getElementById('coordinator-panel');
     if(coordinator?.open)coordinator.setOpen(false);
   }
@@ -2651,13 +2664,35 @@ document.getElementById("btn-auth").onclick = ()=>{
 };
 
 /* ================= 已取消托盘 ================= */
+function closeTray(restoreFocus=false){
+  const tray = document.getElementById("tray");
+  const focusedInside = tray.contains(document.activeElement);
+  tray.classList.remove("open");
+  const trigger = document.getElementById("btn-tray");
+  trigger.classList.remove("on");
+  trigger.setAttribute("aria-expanded", "false");
+  if(restoreFocus && focusedInside) document.getElementById("btn-settings").focus();
+}
 document.getElementById("btn-tray").onclick = ()=>{
   const tray = document.getElementById("tray");
   const open = !tray.classList.contains("open");
+  if(!open){ closeTray(); return; }
   tray.classList.toggle("open", open);
   document.getElementById("btn-tray").classList.toggle("on", open);
-  if(open) closeSettings();
+  document.getElementById("btn-tray").setAttribute("aria-expanded", "true");
+  closeSettings();
+  document.getElementById("tray-close").focus();
 };
+document.getElementById("tray-close").onclick = ()=>closeTray(true);
+document.addEventListener("click", e=>{
+  if(!e.target.closest("#tray, #btn-tray")) closeTray();
+}, true);
+document.addEventListener("keydown", e=>{
+  if(e.key!=="Escape" || e.defaultPrevented || e.isComposing || !document.getElementById("tray").classList.contains("open")) return;
+  if(e.target.closest('input, textarea, [contenteditable="true"]') || document.querySelector("dialog[open]")) return;
+  e.preventDefault();
+  closeTray(true);
+});
 document.getElementById("btn-link-repo").onclick = async ()=>{
   await linkRepo();
   closeSettings();
@@ -4620,7 +4655,7 @@ async function installCoordinatorPanel(sync){
   const setPanelOpen=open=>{
     panel.open=open;panel.toggleAttribute('open',open);
     if(open){
-      openBugPanel(false);document.getElementById('tray').classList.remove('open');
+      openBugPanel(false);closeTray();
       inspector.append(panel);inspector.classList.add('coordinator-open');
     }else{
       clearTimeout(timer);history.hidden=true;historyToggle.setAttribute('aria-expanded','false');inspector.classList.remove('coordinator-open');document.body.append(panel);renderDetail();
@@ -5127,6 +5162,69 @@ async function installCoordinatorPanel(sync){
   window.addEventListener('pagehide',()=>{stopped=true;clearTimeout(timer);setPlanningVisible(false);setTyping(false);});
   window.addEventListener('pageshow',()=>{stopped=false;if(panel.open) void refresh();});
 }
+function installDeviceApprovals(sync){
+  if(!sync.config?.interfaceCapabilities?.deviceAuthorization) return;
+  const trigger=document.getElementById('btn-device-approvals'), panel=document.getElementById('device-approvals');
+  const status=document.getElementById('device-approvals-status'), list=document.getElementById('device-approval-list');
+  trigger.hidden=false;
+  let running=false, deciding=false, stopped=false, refreshFailed=false, renderedRequests=null;
+  const projectId=sync.config.root.slice('cloud:'.length);
+  const errorLabel=(error,decision=false)=>t(error?.code==='UNAUTHORIZED'?'deviceLoginRequired':error?.reason==='repository-access-revoked'?'deviceAccessRevoked':error?.code==='FORBIDDEN'?'deviceTicketRefresh':error?.code==='NOT_FOUND'?'deviceScopeUnavailable':error?.code==='CONFLICT'?'deviceAlreadyDecided':decision&&!error?.serverResponse?'deviceDecisionUnknown':'deviceApprovalsFailed');
+  const refresh=async()=>{
+    if(running||deciding||stopped)return;
+    const requestedDetailed=panel.open;
+    let fullReadNeeded=false;
+    running=true;
+    try{
+      const data=await sync.call('/api/device-authorizations'+(requestedDetailed?'':'?summary=1'),undefined,'GET','main');
+      if(!Number.isSafeInteger(data.count)||data.count<0||data.count>1000||(requestedDetailed&&!Array.isArray(data.requests)))throw Object.assign(new Error('invalid-request-list'),{code:'UNAVAILABLE',serverResponse:true});
+      if(refreshFailed){status.textContent='';refreshFailed=false;}
+      document.getElementById('device-approval-count').textContent=String(data.count);
+      trigger.title=t('deviceApprovals');
+      if(panel.open&&requestedDetailed){
+        const signature=JSON.stringify(data.requests);
+        if(signature===renderedRequests){for(const button of list.querySelectorAll('button'))button.disabled=false;return;}
+        renderedRequests=signature;
+        list.replaceChildren();
+        for(const request of data.requests||[]){
+          const row=document.createElement('article'), heading=document.createElement('b'), detail=document.createElement('p');
+          heading.textContent=request.label;
+          detail.textContent=[request.repository,t('devicePending'),request.createdAt||t('deviceOld')].join(' · ');
+          row.append(heading,detail);
+          for(const [decision,label] of [['approve','deviceAllow'],['deny','deviceDeny']]){
+            const button=document.createElement('button');button.type='button';button.textContent=t(label);
+            button.onclick=async()=>{
+              if(deciding)return;
+              deciding=true;for(const control of list.querySelectorAll('button'))control.disabled=true;
+              try{
+                const ticket=await sync.call('/api/device-authorizations/'+encodeURIComponent(request.requestId),undefined,'GET','main');
+                if(ticket.status!=='pending'){status.textContent=t('deviceDecisionDone');return;}
+                const response=await fetch('/auth/device/decision',{method:'POST',credentials:'same-origin',body:new URLSearchParams({projectId,userCode:ticket.userCode,csrf:ticket.csrf,decision}),signal:AbortSignal.timeout(10000)});
+                if(!response.ok){const error=await response.json().catch(()=>({}));throw Object.assign(new Error('decision-rejected'),{code:error.error?.code,reason:error.error?.reason,serverResponse:true});}
+                status.textContent=t('deviceDecisionDone');
+              }catch(error){status.textContent=errorLabel(error,true);}
+              finally{deciding=false;await refresh();}
+            };
+            row.append(button);
+          }
+          list.append(row);
+        }
+        if(!data.count)list.textContent=t('deviceApprovalsEmpty');
+      }else if(panel.open)fullReadNeeded=true;
+    }catch(error){refreshFailed=true;for(const button of list.querySelectorAll('button'))button.disabled=true;document.getElementById('device-approval-count').textContent='?';trigger.title=errorLabel(error);if(panel.open)status.textContent=errorLabel(error);}
+    finally{running=false;if(fullReadNeeded&&panel.open&&!stopped&&!deciding)void refresh();}
+  };
+  trigger.onclick=()=>{closeTray();document.getElementById('workbench-tools').open=false;status.textContent='';panel.showModal();trigger.setAttribute('aria-expanded','true');document.getElementById('device-approvals-close').focus();void refresh();};
+  document.getElementById('device-approvals-close').onclick=()=>panel.close();
+  document.getElementById('device-approvals-refresh').onclick=()=>void refresh();
+  panel.addEventListener('close',()=>{trigger.setAttribute('aria-expanded','false');document.querySelector('#workbench-tools > summary').focus();});
+  panel.addEventListener('click',event=>{if(event.target!==panel)return;const rect=panel.getBoundingClientRect();if(event.clientX<rect.left||event.clientX>rect.right||event.clientY<rect.top||event.clientY>rect.bottom)panel.close();});
+  window.addEventListener('pagehide',()=>{stopped=true;});
+  window.addEventListener('pageshow',()=>{stopped=false;void refresh();});
+  document.getElementById('workbench-tools').addEventListener('toggle',()=>{if(document.getElementById('workbench-tools').open)void refresh();});
+  refreshDeviceApprovals=refresh;
+  void refresh();
+}
 async function boot(){
   const stored = readStoredUiLang();
   if(stored) uiLang = stored;
@@ -5150,9 +5248,11 @@ async function boot(){
     pending:()=>{ for(const id of ['nodes','links','currents']) document.getElementById(id)?.replaceChildren(); },
     apply:doc=>{ applyingServerMap=true; try{ applyMapDoc(doc); renderAll(); }finally{ applyingServerMap=false; } },
     setAccess:setWorkbenchAccess,
-    statusChanged:()=>renderAll()
+    statusChanged:()=>renderAll(),
+    refreshDeviceApprovals:()=>refreshDeviceApprovals?.()
   });
   const connected=await workbenchSync.start();
+  installDeviceApprovals(workbenchSync);
   if(connected) installCoordinatorPanel(workbenchSync);
   if(!connected){
     if(!window.__CG_SERVER) await loadMapFromHttp();

package/prototype/workbench-sync.mjs

@@ -459,6 +459,7 @@ export class WorkbenchSync {
         else if (head.version !== this.version) await this.receive(head);
         else if (this.status === 'offline') await this.retry();
         await this.refreshTaskStatuses().catch(() => {});
+        void Promise.resolve().then(()=>this.a.refreshDeviceApprovals?.()).catch(()=>{});
       } catch { if (view === this.viewId && !this.disposed) await this.recoverConnection(); }
       finally { this.heartbeatRunning = false; this.scheduleHeartbeat(); }
     }, 10000);

package/prototype/workbench.css

@@ -550,11 +550,13 @@ body.auth-mode .node .add-child,body.auth-mode .node .add-pick{display:none}
 /* ---------- 已取消托盘 ---------- */
 .tray{position:fixed;left:16px;top:calc(var(--chrome-top) + 8px);z-index:29;width:330px;background:var(--paper);
   border:1px solid var(--line);border-radius:10px;box-shadow:0 6px 24px rgba(42,47,43,.14);
-  padding:14px 16px;display:none}
-.tray.open{display:block}
+  padding:14px 16px;display:none;box-sizing:border-box;max-width:calc(100vw - 32px);max-height:calc(100dvh - var(--chrome-top) - 16px)}
+.tray.open{display:flex;flex-direction:column}
+.tray-head{display:flex;align-items:center;justify-content:space-between;gap:8px;flex-shrink:0}
+.tray-head button{width:36px;height:36px;flex-shrink:0;padding:0;font-size:24px;line-height:1;box-shadow:none}
 .tray h3{margin:0 0 3px;font-size:14px}
-.tray p.hint{margin:0 0 10px;font-size:12px;color:var(--muted)}
-.tray ul{list-style:none;margin:0;padding:0}
+.tray p.hint{margin:0 0 10px;font-size:12px;color:var(--muted);flex-shrink:0}
+.tray ul{list-style:none;margin:0;padding:0;min-height:0;overflow:auto}
 .tray li{padding:9px 0;border-top:1px solid var(--line)}
 .tray li:first-child{border-top:0}
 .tray .t-title{font-size:13px;color:var(--muted);text-decoration:line-through}
@@ -563,6 +565,13 @@ body.auth-mode .node .add-child,body.auth-mode .node .add-pick{display:none}
 .tray .t-actions .danger:hover{border-color:var(--red);color:var(--red)}
 .tray .confirm-row{display:flex;align-items:center;gap:6px;margin-top:6px;font-size:12.5px;color:var(--red)}
 .tray .empty{color:var(--muted);font-size:12.5px;padding:6px 0}
+.device-approvals{width:min(520px,calc(100vw - 24px));max-height:calc(100dvh - 24px);box-sizing:border-box;border:2px solid var(--line-ink);border-radius:10px;background:var(--paper);color:var(--ink)}
+.device-approvals[open]{display:flex;flex-direction:column;gap:10px}
+.device-approvals::backdrop{background:rgba(42,47,43,.25)}
+#device-approval-list{min-height:0;overflow:auto;overflow-wrap:anywhere}
+#device-approval-list article{border-top:1px solid var(--line);padding:10px 0}
+#device-approval-list button{margin:4px 8px 0 0}
+#device-approvals-refresh{flex-shrink:0}
 
 /* ---------- 未修 Bug 面板 ---------- */
 #btn-bugs.on,#btn-todos.on,#btn-coordinator[aria-expanded="true"]{background:var(--yellow);font-weight:800}
@@ -896,7 +905,7 @@ html.cg-phone .bug-panel{
   padding-bottom:calc(16px + var(--safe-bottom));
 }
 html.cg-phone .tray{
-  left:8px;right:8px;width:auto;max-height:min(52vh,420px);overflow:auto;
+  left:8px;right:8px;width:auto;max-width:calc(100vw - 16px);max-height:min(52vh,420px,calc(100dvh - var(--chrome-top) - 16px));
   z-index:32
 }
 html.cg-phone .node.module{width:min(252px,86vw);max-width:min(252px,86vw)}

package/prototype/workbench.html

@@ -84,6 +84,7 @@
     <button class="auth-btn" id="btn-auth" data-i18n-title="authMode" title="授权模式" aria-label="授权模式">🔑</button>
     <button class="tray-btn" id="btn-bugs">🐞 Bug (<span id="bug-count">0</span>)</button>
     <button class="tray-btn" id="btn-todos">TODO (<span id="todo-count">0</span>)</button>
+    <button type="button" class="tray-btn" id="btn-device-approvals" aria-expanded="false" aria-controls="device-approvals" hidden><span data-i18n="deviceApprovals">设备连接申请</span> (<span id="device-approval-count">0</span>)</button>
       </div>
     </details>
     <button type="button" class="tray-btn" id="btn-coordinator" aria-expanded="false" hidden>Coordinator</button>
@@ -110,7 +111,7 @@
           <div class="rel-toggle" id="lens-toggle" data-i18n-title="lensTitle" title="首次建图：候选模块摆在画布上，与主节点无连线；选中一个，它才挂到主节点下。">
             <button type="button" id="btn-lens" aria-pressed="false" data-i18n="lensMode">第一层候选</button>
           </div>
-          <button class="tray-btn" id="btn-tray">🗂 <span data-i18n="cancelled">已取消</span> (<span id="tray-count">0</span>)</button>
+          <button type="button" class="tray-btn" id="btn-tray" aria-expanded="false" aria-controls="tray">🗂 <span data-i18n="cancelled">已取消</span> (<span id="tray-count">0</span>)</button>
           <button type="button" class="tray-btn" id="btn-link-repo" hidden data-i18n="linkRepo" data-i18n-title="linkRepoTitle" title="选带 SKILL.md 的仓库根，改图可以写回 map.json">连接仓库</button>
         </div>
       </div>
@@ -190,9 +191,19 @@
   </div>
 </div>
 <div id="dot-hint" hidden role="tooltip"></div>
+<dialog id="device-approvals" class="device-approvals" aria-labelledby="device-approvals-title">
+  <div class="tray-head"><h3 id="device-approvals-title" data-i18n="deviceApprovals">设备连接申请</h3><button type="button" id="device-approvals-close" data-i18n-title="deviceApprovalsClose" aria-label="关闭设备连接申请">×</button></div>
+  <p data-i18n="deviceApprovalScope">仅允许你发起的连接：读取本项目 Main、读写自身 Session；不授予管理或 Main 发布权限。</p>
+  <p role="status" id="device-approvals-status"></p>
+  <div id="device-approval-list"></div>
+  <button type="button" id="device-approvals-refresh" data-i18n="deviceApprovalsRefresh">刷新申请</button>
+</dialog>
 
-<div class="tray" id="tray">
-  <h3 data-i18n="trayTitle">已取消的提议</h3>
+<div class="tray" id="tray" role="region" aria-labelledby="tray-title">
+  <div class="tray-head">
+    <h3 id="tray-title" data-i18n="trayTitle">已取消的提议</h3>
+    <button type="button" id="tray-close" data-i18n-title="trayClose" aria-label="关闭已取消的提议" title="关闭已取消的提议">×</button>
+  </div>
   <p class="hint" data-i18n="trayHint">已隐藏，后续 Agent 不会读到。可重新加入 Context Map，或永久删除。</p>
   <ul id="tray-list"></ul>
 </div>

package/references/cloud-sync-interface.md

@@ -11,6 +11,21 @@ Use `context-guard workbench connect --url <origin> --root <project> --session
 connection. The workbench owns the background connection; never start a separate
 project-wide Map daemon or point a Session at Main to bypass publication.
 
+Current Cloud keeps pending browser-device approval requests until a human decides.
+The CLI negotiates this explicitly and reuses the same private request after a
+stopped invocation or a later retry; the displayed code does not expire merely
+because ten minutes passed. Each HTTP request still has a 15-second limit. Stop
+the CLI to stop waiting; run the same connection command to resume. An approved
+request has a separate, finite claim window, and older Clouds retain their actual
+finite expiry. Upgrade an older Skill for persistent waiting.
+
+An uncertain claim never automatically creates another request or issues another
+credential. It preserves the request and reports failure. After a definite
+rejection or already-claimed receipt, a later explicit connection command starts
+fresh browser approval; it cannot bypass the human decision. None of this changes
+Session identity, existing device permissions, credential renewal or native Hook
+trust.
+
 Local edits enter a durable outbox. Cloud changes are read through events with
 heartbeat recovery. Receipts, queues and cursors remain isolated per Session:
 

package/references/server-memory.md

@@ -75,10 +75,18 @@ Connect once using `context-guard workbench connect --root <project> --url
 URL and code; the human signs in to Cloud and confirms the project/device in the
 browser. The waiting backend saves the device credential without exposing it or
 the password to the Agent. Without `--wait`, the command returns the link at once;
-rerun the same command after approval to finish. Requests expire after ten minutes.
-The backend counts the returned `expiresIn` seconds locally; Cloud's absolute
-`expiresAt` must not require the computer and server clocks to agree.
-Rejection/expiry requires a new request. A claimed reply lost before it was saved
+rerun the same command after approval to finish. Pending requests remain until a
+human allows or denies them. The authenticated project's Workbench Tools exposes
+its device connection requests; this is not the host's tool-execution approval.
+New clients negotiate `X-Context-Guard-Device-Grant: persistent-v1` and receive
+`persistent:true`, `expiresAt:null`, `expiresIn:null` while pending. Older clients
+receive a finite waiting budget and may stop after ten minutes; that does not
+expire or remove the server request. Upgrade the client for persistent waiting.
+An approved request still has a finite one-time claim window. Decision form
+tickets, browser login cookies and issued device credentials retain their own
+expiry and authorization rules. Finite client budgets are counted locally;
+Cloud's absolute `expiresAt` must not require the computer and server clocks to agree.
+Rejection/claim expiry requires a new request. A claimed reply lost before it was saved
 also requires new authorization; consumed grants are never replayed. This is a
 browser device-pairing flow, not a claim of full OAuth interoperability.
 Explicit `--input <private-file|->` remains a compatibility login; JSON contains

package/scripts/workbench/browser-login.mjs

@@ -5,11 +5,21 @@ import { performance } from 'node:perf_hooks';
 import { atomicWrite, encode, readJSON, withFileLock, pause } from '../shared/io.mjs';
 import { fail } from '../shared/protocol.mjs';
 
+const terminalReasons = new Set(['authorization-already-claimed', 'authorization-denied', 'authorization-expired', 'repository-access-revoked']);
+function lifetime(data) {
+  if (data.persistent === true && data.status === 'pending' && data.expiresAt === null && data.expiresIn === null) return { persistent: true, expiresAt: null };
+  if (data.persistent !== undefined && data.persistent !== false || data.persistent === false && data.status !== 'approved' ||
+      typeof data.expiresAt !== 'string' || !Number.isFinite(Date.parse(data.expiresAt)) || !Number.isInteger(data.expiresIn) || data.expiresIn <= 0 || data.expiresIn > 600) {
+    fail('UNAVAILABLE', 'Cloud returned an invalid authorization lifetime');
+  }
+  return { persistent: false, expiresAt: new Date(Date.now() + data.expiresIn * 1000).toISOString() };
+}
+
 async function request(origin, route, input, fetcher, timeoutMs = 15000) {
   let response;
   try {
     response = await fetcher(new URL(route, origin), { method: 'POST', redirect: 'error', signal: AbortSignal.timeout(timeoutMs),
-      headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(input) });
+      headers: { 'Content-Type': 'application/json', ...(route.endsWith('/start') ? { 'X-Context-Guard-Device-Grant': 'persistent-v1' } : {}) }, body: JSON.stringify(input) });
   } catch (error) {
     const beforeConnection = ['ENOTFOUND', 'ECONNREFUSED', 'UND_ERR_CONNECT_TIMEOUT'].includes(error?.cause?.code || error?.code);
     fail('UNAVAILABLE', route.endsWith('/poll') && !beforeConnection ? 'Authorization claim outcome is unknown; explicitly retry browser authorization' : 'Cloud authorization is unavailable; retry the same connection command',
@@ -24,7 +34,8 @@ async function request(origin, route, input, fetcher, timeoutMs = 15000) {
     result = JSON.parse(Buffer.concat(chunks).toString('utf8'));
   } catch (error) { if (error.code === 'TOO_LARGE') throw error; fail('UNAVAILABLE', 'Cloud authorization reply was interrupted'); }
   if (!response.ok || result?.ok !== true) fail(result?.error?.code || 'UNAVAILABLE', result?.error?.message || 'Cloud authorization failed',
-    { retryableConnection: [502, 503, 504].includes(response.status) && result?.error?.code === 'UNAVAILABLE' && result.error.retryable === true });
+    { retryableConnection: [502, 503, 504].includes(response.status) && result?.error?.code === 'UNAVAILABLE' && result.error.retryable === true,
+      ...(terminalReasons.has(result?.error?.reason) ? { reason: result.error.reason } : {}) });
   if (!result.data || typeof result.data !== 'object') fail('UNAVAILABLE', 'Cloud returned an invalid authorization reply');
   return { data: result.data, credential: response.headers.get('x-context-guard-credential') };
 }
@@ -39,6 +50,15 @@ export async function browserLogin(device, { repository, repositoryId, wait = fa
   const checkDeadline = () => {
     if (wait && clock() >= deadline) fail('UNAUTHORIZED', 'Browser authorization expired; retry the connection command', { reason: 'authorization-wait-expired' });
   };
+  const recordFailure = async (pending, error, phase) => {
+    // Keep the exact request after uncertain claims. Only a later explicit
+    // invocation may replace a definitively rejected request for fresh approval.
+    const terminal = ['UNAUTHORIZED', 'FORBIDDEN'].includes(error.code) && error.details?.reason !== 'authorization-wait-expired' &&
+      (phase === 'poll' || terminalReasons.has(error.details?.reason));
+    await atomicWrite(file, encode({ ...pending, ...(terminal ? { status: error.code } : {}),
+      lastFailure: { code: ['UNAUTHORIZED', 'FORBIDDEN', 'UNAVAILABLE', 'UPGRADE_REQUIRED', 'TOO_LARGE'].includes(error.code) ? error.code : 'UNAVAILABLE',
+        ...(terminalReasons.has(error.details?.reason) ? { reason: error.details.reason } : {}), at: new Date().toISOString() } }));
+  };
   const authorize = async (route, input) => {
     for (let attempt = 0; attempt < 3; attempt++) {
       checkDeadline();
@@ -72,36 +92,45 @@ export async function browserLogin(device, { repository, repositoryId, wait = fa
       }
       let pending = await readJSON(file, null);
       checkDeadline();
-      if (grant && ['deviceCode', 'verificationUrl', 'userCode', 'expiresAt', 'origin', 'repository', 'repositoryId'].some(key => pending?.[key] !== grant[key])) fail('CONFLICT', 'Browser authorization changed; retry the connection command');
-      if (!pending?.deviceCode || pending.origin !== device.origin || pending.repository !== repository || pending.repositoryId !== repositoryId || !Number.isFinite(Date.parse(pending.expiresAt)) || !grant && Date.parse(pending.expiresAt) <= Date.now()) {
+      if (grant && ['deviceCode', 'verificationUrl', 'userCode', 'persistent', 'expiresAt', 'origin', 'repository', 'repositoryId'].some(key => pending?.[key] !== grant[key])) fail('CONFLICT', 'Browser authorization changed; retry the connection command');
+      if (!pending?.deviceCode || pending.origin !== device.origin || pending.repository !== repository || pending.repositoryId !== repositoryId || !grant && ['UNAUTHORIZED', 'FORBIDDEN'].includes(pending.status)) {
+        const previousOutcome = pending?.lastFailure;
         pending = { origin: device.origin, repository, repositoryId, deviceCode: randomBytes(32).toString('base64url'), label: String(label).slice(0, 80),
-          expiresAt: new Date(Date.now() + 600000).toISOString() };
+          expiresAt: new Date(Date.now() + 600000).toISOString(), ...(previousOutcome ? { previousOutcome } : {}) };
         await atomicWrite(file, encode(pending));
       }
-      if (!pending.verificationUrl) {
+      if (pending.verificationUrl && !(pending.persistent === true && pending.expiresAt === null) &&
+          (pending.persistent !== undefined && pending.persistent !== false || !Number.isFinite(Date.parse(pending.expiresAt)))) fail('UNAVAILABLE', 'Stored authorization has an invalid lifetime');
+      if (!pending.verificationUrl || !grant && pending.persistent !== true && Date.parse(pending.expiresAt) <= Date.now()) {
         const identity = await device.identity();
-        const { data } = await authorize('/api/auth/device/start', { repository, clientId: identity.clientId, deviceCode: pending.deviceCode, label: pending.label });
+        let data;
+        try { ({ data } = await authorize('/api/auth/device/start', { repository, clientId: identity.clientId, deviceCode: pending.deviceCode, label: pending.label })); }
+        catch (error) { await recordFailure(pending, error, 'start'); throw error; }
         const verification = new URL(data.verificationPath, device.origin);
-        if (verification.origin !== device.origin || verification.pathname !== '/connect' || !/^[A-F0-9]{4}-[A-F0-9]{4}$/.test(data.userCode) || verification.searchParams.get('code') !== data.userCode || !Number.isFinite(Date.parse(data.expiresAt)) || !Number.isInteger(data.expiresIn) || data.expiresIn <= 0 || data.expiresIn > 600) fail('UNAVAILABLE', 'Cloud returned an invalid authorization link');
-        pending = { ...pending, verificationUrl: verification.href, userCode: data.userCode, expiresAt: new Date(Date.now() + data.expiresIn * 1000).toISOString() };
+        if (verification.origin !== device.origin || verification.pathname !== '/connect' || !/^[A-F0-9]{4}-[A-F0-9]{4}$/.test(data.userCode) || verification.searchParams.get('code') !== data.userCode) fail('UNAVAILABLE', 'Cloud returned an invalid authorization link');
+        pending = { ...pending, verificationUrl: verification.href, userCode: data.userCode, ...lifetime(data) };
         await atomicWrite(file, encode(pending));
       }
-      const safe = { connected: false, authorizationRequired: true, verificationUrl: pending.verificationUrl, userCode: pending.userCode, expiresAt: pending.expiresAt };
+      const safe = { connected: false, authorizationRequired: true, verificationUrl: pending.verificationUrl, userCode: pending.userCode,
+        persistent: pending.persistent === true, expiresAt: pending.expiresAt };
       if (wait && !grant) {
-        // A displayed grant and this invocation's budget never renew in a wait loop.
-        deadline = Math.min(deadline, clock() + Math.max(0, Date.parse(pending.expiresAt) - Date.now()));
+        // Only an explicitly negotiated pending grant has no approval deadline.
+        // Finite grants keep the original monotonic invocation budget.
+        deadline = pending.persistent === true ? Infinity : Math.min(deadline, clock() + Math.max(0, Date.parse(pending.expiresAt) - Date.now()));
         grant = { ...pending };
       }
       checkDeadline();
       if (first) await onPending(safe);
       let result;
-      try { result = await authorize('/api/auth/device/poll', { deviceCode: pending.deviceCode }); }
+      try {
+        result = await authorize('/api/auth/device/poll', { deviceCode: pending.deviceCode });
+        if (result.data.status === 'pending') return safe;
+        if (!result.credential || result.credential.length < 32 || !result.data.projectId || !result.data.capabilities?.includes('device-memory')) fail('UNAVAILABLE', 'Cloud did not issue a project device connection');
+      }
       catch (error) {
-        if (['UNAUTHORIZED', 'FORBIDDEN'].includes(error.code) && error.details?.reason !== 'authorization-wait-expired') await atomicWrite(file, encode({ status: error.code }));
+        await recordFailure(pending, error, 'poll');
         throw error;
       }
-      if (result.data.status === 'pending') return safe;
-      if (!result.credential || result.credential.length < 32 || !result.data.projectId || !result.data.capabilities?.includes('device-memory')) fail('UNAVAILABLE', 'Cloud did not issue a project device connection');
       await device.saveConnection(result.data, result.credential, { repositoryId });
       await atomicWrite(file, encode({ status: 'connected' }));
       return { connected: true, ...result.data };