@vantran-se/openchamber-web 2.1.1 → 2.2.0

package/server/lib/session-work/runtime.js

@@ -1,7 +1,8 @@
 /**
  * "In work": Jev moves a session into work when real work starts in it, and
- * says when a turn looks like the end of that work. The user closes; this
- * runtime never does. See DOCUMENTATION.md.
+ * says when a turn looks like the end of that work, or handed over changes
+ * worth a look. The user closes; this runtime never does. See
+ * DOCUMENTATION.md.
  *
  * Two moments ask Jev:
  * - a user message was sent (`message.updated`, role user): only while the
@@ -26,9 +27,10 @@ import {
   buildTurnEndRequest,
   decideAssist,
   decideOpen,
+  decideReviewReady,
   decideWrapUp,
 } from './questions.js';
-import { clearSuggestionPatch, openByJevPatch, readWork, suggestDonePatch } from './state.js';
+import { clearSuggestionPatch, offerReviewPatch, openByJevPatch, readWork, suggestDonePatch } from './state.js';
 
 const OPENCHAMBER_SETTINGS_FILE = path.join(
   process.env.OPENCHAMBER_DATA_DIR
@@ -37,17 +39,20 @@ const OPENCHAMBER_SETTINGS_FILE = path.join(
   'settings.json',
 );
 
-/** Both default on; read at every use so a change applies without a restart. */
+/** In work and auto-open default on, the review offer off; read at every use so a change applies without a restart. */
 const readSessionWorkSettings = () => {
   const settings = readMergedSettingsSync({ fs, path, settingsFilePath: OPENCHAMBER_SETTINGS_FILE });
   return {
     enabled: settings.sessionWorkEnabled !== false,
     autoOpen: settings.sessionWorkAutoOpen !== false,
+    reviewOffer: settings.sessionReviewOfferEnabled === true,
   };
 };
 
 const READ_TIMEOUT_MS = 5_000;
 const REQUEST_CHARS = 1_500;
+/** Head and tail of the turn's answer: what was changed sits early, the outcome late. */
+const ANSWER_EDGE_CHARS = 500;
 const SEEN_MESSAGES_LIMIT = 500;
 
 const errorMessage = (error) => (error instanceof Error ? error.message : String(error));
@@ -75,7 +80,7 @@ const reviewSessionSchema = z.object({ openchamber: z.object({ kind: z.literal('
 export function createSessionWorkRuntime({
   buildOpenCodeUrl,
   getOpenCodeAuthHeaders,
-  /** `{ enabled, autoOpen }` as currently saved. */
+  /** `{ enabled, autoOpen, reviewOffer }` as currently saved. */
   getSettings = readSessionWorkSettings,
   /** The classification provider's endpoint, or null when there is no Jev. */
   classifierEndpoint,
@@ -98,12 +103,12 @@ export function createSessionWorkRuntime({
   };
   let stopped = false;
   const seenMessages = new Set();
-  // Sessions where this process wrote a done hint, so a new turn can retire it
+  // Sessions where this process wrote a hint, so a new turn can retire it
   // without reading every session's metadata at every turn start.
   const suggested = new Map();
   // A turn counter per session, moved by every turn start and every new user
   // message. A turn-end check captures it before asking Jev and writes the
-  // done hint only if no newer turn began in the meantime: a late answer about
+  // hint only if no newer turn began in the meantime: a late answer about
   // the previous turn must not land on the next one.
   // Values come from one process-wide counter, so they never repeat: a session
   // evicted from the bounded map reads 0, which no pending check captured
@@ -139,7 +144,6 @@ export function createSessionWorkRuntime({
     const session = await client.session.get({ sessionID: sessionId }, { signal });
     if (session?.id === sessionId) lineage?.remember(sessionId, session.parentID ?? null);
     if (session?.id !== sessionId || session.parentID) return null;
-    if (session.metadata?.openchamber?.adopted !== true) return null;
     if (isChatDirectory(session.location?.directory ?? session.directory)) return null;
     if (reviewSessionSchema.safeParse(session.metadata).success) return null;
     if (await isSessionArchived(sessionId)) return null;
@@ -181,7 +185,7 @@ export function createSessionWorkRuntime({
     const directory = suggested.get(sessionId);
     suggested.delete(sessionId);
     Promise.resolve(updateMetadata(sessionId, clearSuggestionPatch, { directory }))
-      .catch((error) => console.warn('[session-work] could not retire a done hint:', errorMessage(error)));
+      .catch((error) => console.warn('[session-work] could not retire a hint:', errorMessage(error)));
   };
 
   const processPayload = (payload, directoryHint = '') => {
@@ -217,7 +221,7 @@ export function createSessionWorkRuntime({
   const evaluateTurnEnd = async ({ sessionId, directory, assist }) => {
     if (stopped || lineage?.isChild(sessionId) === true) return null;
     const settings = getSettings();
-    if (!settings.enabled && !assist.recap && !assist.suggestion) return null;
+    if (!settings.enabled && !settings.reviewOffer && !assist.recap && !assist.suggestion) return null;
     // Never capture 0: an evicted session also reads 0.
     if (!turnGenerations.has(sessionId)) advanceTurn(sessionId);
     const generation = turnGeneration(sessionId);
@@ -232,6 +236,7 @@ export function createSessionWorkRuntime({
       const ask = {
         open: settings.enabled && settings.autoOpen && work?.state !== 'open',
         wrapUp: settings.enabled && work?.state === 'open',
+        reviewReady: settings.reviewOffer,
         recap: assist.recap,
         nextStep: assist.suggestion,
       };
@@ -241,7 +246,7 @@ export function createSessionWorkRuntime({
       const request = buildTurnEndRequest({
         history: turnsToHistory(context.turns.slice(0, -1)),
         request: excerptHead(turn.user.text, REQUEST_CHARS),
-        answer: excerptHeadTail(turn.assistant.text, 300, 300),
+        answer: excerptHeadTail(turn.assistant.text, ANSWER_EDGE_CHARS, ANSWER_EDGE_CHARS),
         ask,
       });
       if (!request) return null;
@@ -251,12 +256,16 @@ export function createSessionWorkRuntime({
         const requestAt = turn.user.created ?? now();
         await updateMetadata(sessionId, (metadata) => openByJevPatch(metadata, { requestAt, now: now() }), { directory });
       }
-      if (ask.wrapUp && decideWrapUp(answers)) {
+      // Looks done wins over a review offer from the same turn.
+      const suggest = ask.wrapUp && decideWrapUp(answers)
+        ? suggestDonePatch
+        : ask.reviewReady && decideReviewReady(answers) ? offerReviewPatch : null;
+      if (suggest) {
         // Decided at write time: a turn that started while Jev was answering
         // makes this answer about an older turn.
         const { changed } = await updateMetadata(
           sessionId,
-          (metadata) => (turnGeneration(sessionId) === generation ? suggestDonePatch(metadata, { now: now() }) : null),
+          (metadata) => (turnGeneration(sessionId) === generation ? suggest(metadata, { now: now() }) : null),
           { directory },
         );
         if (changed) markSuggested(sessionId, directory);

package/server/lib/session-work/runtime.test.js

@@ -18,12 +18,11 @@ const answeredTurn = [
   ...settledPair,
 ];
 
-const stubOpenCode = ({ session, records = answeredTurn } = {}) => {
-  const sessionRecord = session ?? { metadata: { openchamber: { adopted: true } } };
+const stubOpenCode = ({ session = {}, records = answeredTurn } = {}) => {
   const fetchMock = vi.fn(async (input) => {
     const url = new URL(String(input));
     let body;
-    if (url.pathname === '/api/session/ses_1') body = { data: { id: 'ses_1', ...sessionRecord } };
+    if (url.pathname === '/api/session/ses_1') body = { data: { id: 'ses_1', ...session } };
     else if (url.pathname === '/api/session/ses_1/message') body = { data: records, cursor: {} };
     else throw new Error(`unexpected ${url.pathname}`);
     return new Response(JSON.stringify(body), { status: 200, headers: { 'content-type': 'application/json' } });
@@ -32,7 +31,7 @@ const stubOpenCode = ({ session, records = answeredTurn } = {}) => {
   return fetchMock;
 };
 
-const makeRuntime = ({ metadata = { openchamber: { adopted: true } }, answers = {}, askError = null, settings = {}, endpoint = ENDPOINT, lineage = null } = {}) => {
+const makeRuntime = ({ metadata = {}, answers = {}, askError = null, settings = {}, endpoint = ENDPOINT, lineage = null } = {}) => {
   const records = new Map([['ses_1', metadata]]);
   const updateMetadata = vi.fn(async (id, decide) => {
     const current = records.get(id) ?? {};
@@ -47,7 +46,7 @@ const makeRuntime = ({ metadata = { openchamber: { adopted: true } }, answers =
   const runtime = createSessionWorkRuntime({
     buildOpenCodeUrl: (fetchPath) => `http://opencode.test${fetchPath}`,
     getOpenCodeAuthHeaders: () => ({}),
-    getSettings: () => ({ enabled: true, autoOpen: true, ...settings }),
+    getSettings: () => ({ enabled: true, autoOpen: true, reviewOffer: true, ...settings }),
     classifierEndpoint: async () => endpoint,
     jev,
     readMetadata: async (id) => records.get(id) ?? {},
@@ -89,24 +88,13 @@ describe('session work decisions', () => {
 });
 
 describe('session work runtime: a message was sent', () => {
-  it('does not send a TUI-only session to Jev', async () => {
-    stubOpenCode({ session: {}, records: [{ id: 'msg_new', type: 'user', text: 'Keep this local' }, ...settledPair] });
-    const { runtime, jev } = makeRuntime({ metadata: {} });
-
-    runtime.processPayload(sent('msg_new', 'Keep this local'));
-    await new Promise((resolve) => setTimeout(resolve, 20));
-
-    expect(jev.ask).not.toHaveBeenCalled();
-  });
-
   it('asks Jev on the new message with the settled turns as history, and opens the session', async () => {
     stubOpenCode({ records: [{ id: 'msg_new', type: 'user', text: 'Now fix the header' }, ...settledPair] });
     const { runtime, jev, records } = makeRuntime({ answers: { change: { noul: 0.95 }, toward_change: { noul: 0.9 } } });
 
     runtime.processPayload(sent());
-    await settle(() => records.get('ses_1').openchamber?.work?.state === 'open');
+    await settle(() => records.get('ses_1').openchamber);
 
-    expect(jev.ask).toHaveBeenCalledOnce();
     const [request] = jev.ask.mock.calls[0];
     expect(request.state.request).toBe('Now fix the header');
     expect(request.state.history.map((entry) => entry.role)).toEqual(['user', 'assistant']);
@@ -116,7 +104,7 @@ describe('session work runtime: a message was sent', () => {
 
   it('does not ask again for a session already in work, or for the same message twice', async () => {
     stubOpenCode();
-    const open = makeRuntime({ metadata: { openchamber: { adopted: true, work: { state: 'open' } } } });
+    const open = makeRuntime({ metadata: { openchamber: { work: { state: 'open' } } } });
     open.runtime.processPayload(sent());
     await new Promise((resolve) => setTimeout(resolve, 30));
     expect(open.jev.ask).not.toHaveBeenCalled();
@@ -177,22 +165,22 @@ describe('session work runtime: a turn ended', () => {
     const gate = await runtime.evaluateTurnEnd({ sessionId: 'ses_1', directory: '/repo', assist: { recap: true, suggestion: true } });
 
     expect(jev.ask).toHaveBeenCalledTimes(1);
-    expect(Object.keys(jev.ask.mock.calls[0][0].questions).sort()).toEqual(['change', 'next_step', 'recap', 'toward_change']);
+    expect(Object.keys(jev.ask.mock.calls[0][0].questions).sort()).toEqual(['change', 'next_step', 'recap', 'review_ready', 'toward_change']);
     expect(jev.ask.mock.calls[0][0].state).toMatchObject({ request: 'Implement it', answer: 'Done, try it.' });
     expect(gate).toEqual({ recap: true, suggestion: false });
     expect(records.get('ses_1')).toMatchObject({ openchamber: { work: { state: 'open' } } });
   });
 
-  it('asks only whether the work looks done in a session already in work, and a new turn retires the hint', async () => {
+  it('asks only about the end of the work and a review in a session already in work, and a new turn retires the hint', async () => {
     stubOpenCode();
     const { runtime, jev, records, updateMetadata } = makeRuntime({
-      metadata: { openchamber: { adopted: true, work: { state: 'open', openedAt: 1 } } },
+      metadata: { openchamber: { work: { state: 'open', openedAt: 1 } } },
       answers: { wrap_up: { noul: 0.93 } },
     });
 
     const gate = await runtime.evaluateTurnEnd({ sessionId: 'ses_1', directory: '/repo', assist: { recap: false, suggestion: false } });
 
-    expect(Object.keys(jev.ask.mock.calls[0][0].questions)).toEqual(['wrap_up']);
+    expect(Object.keys(jev.ask.mock.calls[0][0].questions)).toEqual(['wrap_up', 'review_ready']);
     expect(gate).toBeNull();
     expect(records.get('ses_1').openchamber.work.suggestDoneAt).toBeTypeOf('number');
 
@@ -205,10 +193,39 @@ describe('session work runtime: a turn ended', () => {
     expect(updateMetadata).toHaveBeenCalledTimes(2);
   });
 
+  it('offers a review after a turn that changed the project, and looks done wins over it', async () => {
+    stubOpenCode();
+    const open = { openchamber: { work: { state: 'open', openedAt: 1 } } };
+    const review = makeRuntime({ metadata: open, answers: { wrap_up: { noul: 0.2 }, review_ready: { noul: 0.75 } } });
+    await review.runtime.evaluateTurnEnd({ sessionId: 'ses_1', directory: '/repo', assist: { recap: false, suggestion: false } });
+    expect(review.records.get('ses_1').openchamber.reviewOffer.at).toBeTypeOf('number');
+    expect(review.records.get('ses_1').openchamber.work).not.toHaveProperty('suggestDoneAt');
+
+    const both = makeRuntime({ metadata: open, answers: { wrap_up: { noul: 0.9 }, review_ready: { noul: 0.9 } } });
+    await both.runtime.evaluateTurnEnd({ sessionId: 'ses_1', directory: '/repo', assist: { recap: false, suggestion: false } });
+    expect(both.records.get('ses_1').openchamber.work.suggestDoneAt).toBeTypeOf('number');
+    expect(both.records.get('ses_1').openchamber).not.toHaveProperty('reviewOffer');
+  });
+
+  it('offers a review without In work, asks nothing about it when it is off, and a new turn retires it', async () => {
+    stubOpenCode();
+    const solo = makeRuntime({ settings: { enabled: false }, answers: { review_ready: { noul: 0.8 } } });
+    await solo.runtime.evaluateTurnEnd({ sessionId: 'ses_1', directory: '/repo', assist: { recap: false, suggestion: false } });
+    expect(Object.keys(solo.jev.ask.mock.calls[0][0].questions)).toEqual(['review_ready']);
+    expect(solo.records.get('ses_1')).toEqual({ openchamber: { reviewOffer: { at: expect.any(Number) } } });
+    solo.runtime.processPayload({ type: 'session.status', properties: { sessionID: 'ses_1', status: { type: 'busy' } } });
+    await settle(() => !solo.records.get('ses_1').openchamber?.reviewOffer);
+    expect(solo.records.get('ses_1').openchamber).not.toHaveProperty('reviewOffer');
+
+    const off = makeRuntime({ settings: { reviewOffer: false }, answers: { change: { noul: 0.1 } } });
+    await off.runtime.evaluateTurnEnd({ sessionId: 'ses_1', directory: '/repo', assist: { recap: false, suggestion: false } });
+    expect(Object.keys(off.jev.ask.mock.calls[0][0].questions)).not.toContain('review_ready');
+  });
+
   it('drops a late done answer once the next turn started', async () => {
     stubOpenCode();
     const { runtime, jev, records } = makeRuntime({
-      metadata: { openchamber: { adopted: true, work: { state: 'open', openedAt: 1 } } },
+      metadata: { openchamber: { work: { state: 'open', openedAt: 1 } } },
     });
     let answer;
     jev.ask.mockImplementation(() => new Promise((resolve) => { answer = resolve; }));
@@ -239,7 +256,7 @@ describe('session work runtime: a turn ended', () => {
   it('never closes: a closing turn in a session in work only hints', async () => {
     stubOpenCode();
     const { runtime, records } = makeRuntime({
-      metadata: { openchamber: { adopted: true, work: { state: 'open', openedAt: 1 } } },
+      metadata: { openchamber: { work: { state: 'open', openedAt: 1 } } },
       answers: { wrap_up: { noul: 0.99 }, change: { noul: 0 } },
     });
     await runtime.evaluateTurnEnd({ sessionId: 'ses_1', directory: '/repo', assist: { recap: false, suggestion: false } });
@@ -257,9 +274,9 @@ describe('session work runtime: a turn ended', () => {
     expect(updateMetadata).not.toHaveBeenCalled();
   });
 
-  it('makes no call when the feature and both assist fields are off', async () => {
+  it('makes no call when In work, the review offer and both assist fields are off', async () => {
     const fetchMock = stubOpenCode();
-    const { runtime, jev } = makeRuntime({ settings: { enabled: false } });
+    const { runtime, jev } = makeRuntime({ settings: { enabled: false, reviewOffer: false } });
     expect(await runtime.evaluateTurnEnd({ sessionId: 'ses_1', directory: '/repo', assist: { recap: false, suggestion: false } })).toBeNull();
     expect(jev.ask).not.toHaveBeenCalled();
     expect(fetchMock).not.toHaveBeenCalled();

package/server/lib/session-work/state.js

@@ -1,6 +1,7 @@
 /**
  * `metadata.openchamber.work`: whether a session is in work and what Jev
- * currently suggests about it. Every function returns a JSON merge patch for
+ * currently suggests about it; `metadata.openchamber.reviewOffer`: Jev's offer
+ * to look over the last turn's changes, which does not depend on work. Every function returns a JSON merge patch for
  * the session metadata store, or null when nothing changes, so the store can
  * decide against the record as it is at write time.
  *
@@ -19,6 +20,7 @@ const workSchema = z.object({
 });
 
 const metadataSchema = z.object({ openchamber: z.object({ work: workSchema }) });
+const reviewOfferSchema = z.object({ openchamber: z.object({ reviewOffer: z.object({ at: z.number() }) }) });
 
 /** The session's work record, or null when it has none (or a malformed one). */
 export const readWork = (metadata) => metadataSchema.safeParse(metadata).data?.openchamber.work ?? null;
@@ -40,9 +42,13 @@ export const suggestDonePatch = (metadata, { now }) => {
   return patchOf({ suggestDoneAt: now });
 };
 
+/** The turn that just ended handed over changes worth a look; any session. */
+export const offerReviewPatch = (_metadata, { now }) => ({ openchamber: { reviewOffer: { at: now } } });
+
 /** A new turn started: whatever Jev concluded about the last one no longer holds. */
 export const clearSuggestionPatch = (metadata) => {
-  const work = readWork(metadata);
-  if (!work || work.suggestDoneAt === undefined) return null;
-  return patchOf({ suggestDoneAt: null });
+  const patch = {};
+  if (readWork(metadata)?.suggestDoneAt !== undefined) patch.work = { suggestDoneAt: null };
+  if (reviewOfferSchema.safeParse(metadata).success) patch.reviewOffer = null;
+  return Object.keys(patch).length > 0 ? { openchamber: patch } : null;
 };

package/server/lib/session-work/state.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { clearSuggestionPatch, openByJevPatch, readWork, suggestDonePatch } from './state.js';
+import { clearSuggestionPatch, openByJevPatch, readWork, offerReviewPatch, suggestDonePatch } from './state.js';
 
 const withWork = (work) => ({ openchamber: { goal: { id: 'g' }, work } });
 
@@ -31,4 +31,11 @@ describe('session work state', () => {
     expect(clearSuggestionPatch(withWork({ state: 'open', suggestDoneAt: 3 }))).toEqual({ openchamber: { work: { suggestDoneAt: null } } });
     expect(clearSuggestionPatch(withWork({ state: 'open' }))).toBeNull();
   });
+
+  it('offers a review on any session, and a new turn retires both hints', () => {
+    expect(offerReviewPatch({}, { now: 3 })).toEqual({ openchamber: { reviewOffer: { at: 3 } } });
+    expect(clearSuggestionPatch({ openchamber: { reviewOffer: { at: 3 } } })).toEqual({ openchamber: { reviewOffer: null } });
+    expect(clearSuggestionPatch({ openchamber: { work: { state: 'open', suggestDoneAt: 3 }, reviewOffer: { at: 3 } } }))
+      .toEqual({ openchamber: { work: { suggestDoneAt: null }, reviewOffer: null } });
+  });
 });

package/server/lib/shared/DOCUMENTATION.md

@@ -0,0 +1,89 @@
+# Shared Guards Documentation
+
+## Purpose
+
+`packages/web/server/lib/shared/guards.js` holds the small value predicates and
+coercions that several feature modules used to define privately. It is neutral:
+it knows nothing about git, OpenCode, projects, or any other domain, and it
+imports nothing. Consolidating the copies means a value can no longer be a
+string on one route and not a string on another because two files spelled the
+check differently.
+
+Only the dominant, behavior-defining spelling of each guard belongs here.
+Variants that answer differently for real inputs stay with their owner.
+
+## Public exports
+
+- `isString(value)`: `Object.prototype.toString.call(value) === '[object String]'`.
+  True for primitive strings and boxed `String` objects. This is wider than
+  `typeof value === 'string'`, which is why callers that only accept primitives
+  keep their own `typeof` check.
+- `isPlainObject(value)`: true only for a plain `{}`-shaped object. Rejects
+  `null`, arrays, boxed primitives, `Date`, `Map`, class instances, functions,
+  and null-prototype objects (`Object.create(null)`).
+- `isRecord(value)`: true for any non-null, non-array object. Accepts plain
+  objects, class instances, `Date`, `Map`, boxed primitives, and null-prototype
+  objects.
+- Modules that call the predicate `isObjectRecord` import `isRecord` under that
+  local name; the shared module exposes one canonical export.
+- `asNonEmptyString(value)`: trims a string and returns it, or returns `null`
+  when the input is not a string or is empty/whitespace after trimming. The
+  `null` answer (not `''`) keeps "absent" distinguishable from "present".
+
+## Behavior matrix
+
+| input | `isString` | `isPlainObject` | `isRecord` / `isObjectRecord` | `asNonEmptyString` |
+|---|---|---|---|---|
+| `'s'` | true | false | false | `'s'` |
+| `''` | true | false | false | `null` |
+| `'  s  '` | true | false | false | `'s'` |
+| `'   '` | true | false | false | `null` |
+| `new String('s')` | true | false | true | `null` (not a primitive) |
+| `42` / `NaN` | false | false | false | `null` |
+| `null` / `undefined` | false | false | false | `null` |
+| `{}` | false | true | true | `null` |
+| `[]` | false | false | false | `null` |
+| `new Foo()` (class) | false | false | true | `null` |
+| `new Date()` | false | false | true | `null` |
+| `new Map()` | false | false | true | `null` |
+| `Object.create(null)` | false | false | true | `null` |
+
+## What stays out
+
+These look adjacent but are not the same predicate, so each keeps its private
+copy:
+
+- `terminal/runtime.js` and `terminal/shells.js` use `String(value) === value`,
+  which rejects boxed strings and throws on null-prototype objects.
+- `guests/oauth.js`, `opencode/settings-files.js`, and `opencode/shared.js`
+  expose a loose `isPlainObject` that uses `typeof value === 'object'` and so
+  accepts values the strict predicate rejects. They keep their own name and
+  shape; only modules asking for `isRecord` were migrated.
+- `source-control/mutation-executor.js` accepts null-prototype objects under an
+  `isPlainObject` name, and `github/routes.js` /
+  `github/repo/fork-detection.js` classify by `[object Object]`; all three are
+  divergent and stay put.
+- `quota/utils/transformers.js` exports an array-accepting `asObject`; it is not
+  a guard for a record and is out of scope.
+- `projects/project-config.js` owns its config normalization pipeline and keeps
+  it local.
+
+## Re-exported public APIs
+
+The modules below keep their exported names and signatures and now re-export
+the shared functions, so existing importers are unaffected:
+
+- `opencode/config-v2.js`: `isRecord`
+- `linear/parse.js`: `isString`, `isPlainObject`
+- `gitlab/validation.js`: `isString`, `isPlainObject`
+- `quota/utils/transformers.js`: `asNonEmptyString`
+
+## Notes for contributors
+
+- Add a predicate here only when two or more feature modules need the exact
+  same behavior. If a caller needs a stricter or looser answer, keep the
+  variant local and name the difference in a comment.
+- Do not add feature imports to this module. It must stay free of domain
+  dependencies so every runtime can safely depend on it.
+- When a guard's answer changes, update the behavior matrix test beside this
+  file; the test is the contract.

package/server/lib/shared/guards.js

@@ -0,0 +1,53 @@
+/**
+ * Neutral value guards shared across the web server.
+ *
+ * These are intentionally dependency-free and feature-agnostic: they describe
+ * what a value *is*, never what it means. Feature modules that need one of
+ * these predicates should import it from here rather than defining a private
+ * copy, so the same input can never classify differently on two surfaces.
+ *
+ * Only the dominant spelling of each guard lives here. Variants that look
+ * similar but answer differently for real inputs stay with their owner:
+ * `terminal/runtime.js` uses `String(value) === value`, which rejects boxed
+ * strings and throws on null-prototype objects; `guests/oauth.js`,
+ * `opencode/settings-files.js`, and `opencode/shared.js` use a loose
+ * `typeof value === 'object'` object check that classifies differently from
+ * `isPlainObject`; `quota/utils/transformers.js` exports an array-accepting
+ * `asObject`. See DOCUMENTATION.md for the full matrix.
+ */
+
+/**
+ * True for primitive strings and `String` objects (`[object String]`).
+ * This is broader than `typeof value === 'string'`; callers that only want
+ * primitives must check `typeof` themselves.
+ */
+export const isString = (value) => Object.prototype.toString.call(value) === '[object String]';
+
+/**
+ * True only for a plain `{}`-shaped object: not null, not an array, not a
+ * boxed primitive, `Date`, `Map`, class instance, or null-prototype object.
+ * Use this when the value is decoded from JSON or written back to JSON and a
+ * non-plain object would be corrupted by spreading or key enumeration.
+ */
+export const isPlainObject = (value) => typeof value === 'object'
+  && value !== null
+  && !Array.isArray(value)
+  && Object.getPrototypeOf(value) === Object.prototype;
+
+/**
+ * True for any non-null, non-array object: plain objects, class instances,
+ * `Date`, `Map`, boxed primitives, and null-prototype objects. Use this when a
+ * value only needs to be traversable as an object, not spread as JSON.
+ */
+export const isRecord = (value) => Boolean(value && typeof value === 'object' && !Array.isArray(value));
+
+/**
+ * Trim a string, returning `null` when the input is not a string or is empty
+ * after trimming. The `null` (not `''`) answer lets callers distinguish
+ * "absent" from "present".
+ */
+export const asNonEmptyString = (value) => {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+};

package/server/lib/shared/guards.test.js

@@ -0,0 +1,112 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  asNonEmptyString,
+  isPlainObject,
+  isRecord,
+  isString,
+} from './guards.js';
+
+class Example {
+  constructor() {
+    this.value = 1;
+  }
+}
+
+const nullPrototype = Object.assign(Object.create(null), { value: 1 });
+const boxedString = Object('s');
+const label = (value) => {
+  try {
+    return String(value);
+  } catch {
+    return Object.prototype.toString.call(value);
+  }
+};
+
+describe('isString', () => {
+  it('accepts primitive and boxed strings, including the empty string', () => {
+    expect(isString('s')).toBe(true);
+    expect(isString('')).toBe(true);
+    expect(isString('   ')).toBe(true);
+    expect(isString(boxedString)).toBe(true);
+  });
+
+  it('rejects every non-string value', () => {
+    for (const value of [42, 0, NaN, true, null, undefined, [], {}, nullPrototype, new Example(), new Date(), new Map()]) {
+      expect(isString(value), `isString(${label(value)})`).toBe(false);
+    }
+  });
+});
+
+describe('isPlainObject', () => {
+  it('accepts only a plain object literal', () => {
+    expect(isPlainObject({})).toBe(true);
+    expect(isPlainObject({ a: 1 })).toBe(true);
+  });
+
+  it('rejects arrays, primitives, and absent values', () => {
+    for (const value of [[], [1], 42, 0, 's', '', true, null, undefined]) {
+      expect(isPlainObject(value), `isPlainObject(${label(value)})`).toBe(false);
+    }
+  });
+
+  it('rejects values that merely look object-shaped', () => {
+    expect(isPlainObject(boxedString)).toBe(false);
+    expect(isPlainObject(new Example())).toBe(false);
+    expect(isPlainObject(new Date())).toBe(false);
+    expect(isPlainObject(new Map())).toBe(false);
+    expect(isPlainObject(nullPrototype)).toBe(false);
+  });
+});
+
+describe('isRecord', () => {
+  it('accept every non-null, non-array object', () => {
+    for (const value of [{}, { a: 1 }, boxedString, new Example(), new Date(), new Map(), nullPrototype]) {
+      expect(isRecord(value), `isRecord(${label(value)})`).toBe(true);
+    }
+  });
+
+  it('reject arrays, primitives, and absent values', () => {
+    for (const value of [[], [1], 42, 0, NaN, 's', '', true, null, undefined]) {
+      expect(isRecord(value), `isRecord(${label(value)})`).toBe(false);
+    }
+  });
+});
+
+describe('asNonEmptyString', () => {
+  it('trims a string and returns the trimmed value', () => {
+    expect(asNonEmptyString('s')).toBe('s');
+    expect(asNonEmptyString('  s  ')).toBe('s');
+    expect(asNonEmptyString('\n\ttab\t\n')).toBe('tab');
+  });
+
+  it('returns null for empty, whitespace-only, and non-string values', () => {
+    for (const value of ['', '   ', '\n\t', 42, 0, NaN, true, null, undefined, {}, [], boxedString]) {
+      expect(asNonEmptyString(value), `asNonEmptyString(${label(value)})`).toBeNull();
+    }
+  });
+});
+
+describe('re-exported public APIs', () => {
+  it('linear/parse.js re-exports the shared predicates', async () => {
+    const parse = await import('../linear/parse.js');
+    expect(parse.isString).toBe(isString);
+    expect(parse.isPlainObject).toBe(isPlainObject);
+  });
+
+  it('gitlab/validation.js re-exports the shared predicates', async () => {
+    const validation = await import('../gitlab/validation.js');
+    expect(validation.isString).toBe(isString);
+    expect(validation.isPlainObject).toBe(isPlainObject);
+  });
+
+  it('opencode/config-v2.js re-exports the shared isRecord', async () => {
+    const configV2 = await import('../opencode/config-v2.js');
+    expect(configV2.isRecord).toBe(isRecord);
+  });
+
+  it('quota/utils/transformers.js re-exports the shared asNonEmptyString', async () => {
+    const transformers = await import('../quota/utils/transformers.js');
+    expect(transformers.asNonEmptyString).toBe(asNonEmptyString);
+  });
+});

package/server/lib/skills-catalog/DOCUMENTATION.md

@@ -38,17 +38,17 @@ The following functions are exported and used by the web server:
 - `parseSkillRepoSource(source, { subpath })`: Parse git repository source string into structured object with SSH/HTTPS clone URLs, normalized repo, and effective subpath. Supports SSH URLs, HTTPS URLs, and shorthand `owner/repo[/subpath]` format.
 
 ### Git Repository Scanning (`scan.js`)
-- `scanSkillsRepository({ source, subpath, defaultSubpath, identity })`: Scan git repository for skills by cloning and analyzing SKILL.md files. Returns array of skill items with metadata.
+- `scanSkillsRepository({ source, subpath, defaultSubpath, identity, credentialResolver })`: Scan a Git repository for skills by cloning it and reading its `SKILL.md` files. Account identities use their connected HTTPS credential, SSH identities use their managed key, anonymous identities use credential-free HTTPS, and no identity (labelled "This machine" in the catalog dialog) uses the server's own Git configuration and credential helpers.
 
 ### Git Repository Installation (`install.js`)
-- `installSkillsFromRepository({ source, subpath, defaultSubpath, identity, scope, targetSource, workingDirectory, userSkillDir, selections, conflictPolicy, conflictDecisions })`: Install skills from git repository. Supports user/project scopes, opencode/agents targets, conflict resolution (prompt/skipAll/overwriteAll), and sparse checkout for efficiency.
+- `installSkillsFromRepository({ source, subpath, defaultSubpath, identity, credentialResolver, scope, targetSource, workingDirectory, userSkillDir, selections, conflictPolicy, conflictDecisions })`: Install selected skills from a Git repository. It uses the same identity transports as scanning and supports user/project scopes, opencode/agents targets, conflict resolution (prompt/skipAll/overwriteAll), and sparse checkout.
 
 ## Internal Helpers
 
 The following functions are internal helpers used by exported functions:
 
 ### Git Helpers (`git.js`)
-- `runGit(args, options)`: Execute git command with optional SSH identity, timeout, and max buffer. Returns `{ ok, stdout, stderr, message, code, signal }`.
+- `runGit(args, options)`: Execute a Git command with optional managed identity, credential resolver, timeout, and max buffer. HTTPS tokens go through the one-use local credential broker and never enter Git's arguments. Returns `{ ok, stdout, stderr, message, code, signal }`.
 - `looksLikeAuthError(message)`: Detect if error message indicates authentication failure (permission denied, publickey, etc.).
 - `assertGitAvailable()`: Check if git is available in PATH.
 
@@ -62,7 +62,7 @@ The following functions are internal helpers used by exported functions:
 - `normalizeUserSkillDir(userSkillDir)`: Normalize the user skill directory path (handles the legacy `skill` directory in the XDG config location, or `~/.config/opencode/skill` when XDG is unset, by selecting the plural `skills` directory when appropriate).
 
 ### Git Clone Helpers (`install.js`, `scan.js`)
-- `cloneRepo({ cloneUrl, identity, tempDir })`: Clone git repository with preferred partial clone (`--filter=blob:none`) and fallback. Uses non-interactive mode.
+- `cloneRepo({ cloneUrl, identity, credentialResolver, tempDir, ref })`: Clone git repository with preferred partial clone (`--filter=blob:none`) and fallback, on `ref` when the source names one. Uses non-interactive mode.
 
 ### SKILL.md Parsing (`scan.js`)
 - `parseSkillMd(content)`: Parse YAML frontmatter from SKILL.md content. Returns `{ ok, frontmatter, warnings }`.
@@ -111,11 +111,14 @@ The following functions are internal helpers used by exported functions:
 - Skill names are derived from directory basenames for git repos.
 - Invalid names result in non-installable skills with appropriate warnings.
 
-### Git Cloning Strategy
-- Use sparse checkout to minimize clone size: `sparse-checkout init`, `sparse-checkout set`, `checkout HEAD`.
+### Git cloning strategy
+- Use sparse checkout to minimize checkout size: `sparse-checkout init`, `sparse-checkout set`, `checkout HEAD`.
+- Keep managed credentials scoped to the selected provider endpoint. Do not fall back to System Git after a selected identity fails, and refuse a selected identity that names no credential.
+- Only commands that reach the remote resolve the identity: the clone, the `checkout`, and the `show` fallback in `scan.js`, which fetch blobs lazily from the partial clone. Local commands (`sparse-checkout`, `ls-files`, `ls-tree`) run without it.
+- Managed HTTPS and anonymous runs point `HOME`, `USERPROFILE`, and `XDG_CONFIG_HOME` at the null device, so an ambient `~/.netrc` cannot sign in as another account. SSH runs keep `HOME` for `known_hosts`.
 - Preferred clone uses `--depth=1 --filter=blob:none` for partial clone with fallback to `--depth=1`.
 - Always use non-interactive mode (`GIT_TERMINAL_PROMPT=0`) to avoid hangs.
-- SSH keys are injected via `core.sshCommand` in git config.
+- Managed SSH keys are injected as `-c core.sshCommand=<wrapper>` through the shared SSH wrapper; the operation's key copy is removed after the run.
 
 ### Conflict Resolution
 - Installation checks for existing skills before downloading/cloning.
@@ -133,7 +136,6 @@ The following functions are internal helpers used by exported functions:
 ### Security Considerations
 - Path traversal protection in `copyDirectoryNoSymlinks`: resolves real paths and checks containment.
 - Symlinks are explicitly rejected to prevent escape from skill directory.
-- SSH key paths are trimmed but not escaped in `git.js` (assumes safe input from profiles).
 - Temporary directories are cleaned up in `finally` blocks.
 
 ### Error Handling