@astrale-os/cli 1.0.0-beta.30 → 1.0.0-beta.32

package/README.md

@@ -105,7 +105,11 @@ astrale update
 from `astrale-os/cli` is installed and healthy, and follows the beta channel by default. It reports
 whether the skill pass was unchanged, installed, updated, or repaired. Use `--check`,
 `--channel <channel>`, or `--version <version>` to control the CLI release target; skills always
-track the repository's current `main` source. `--no-skills` is the explicit opt-out.
+resolve the repository's current `main` once, verify the installed trees against that commit, and
+stamp the exact revision/tree binding into the Astrale-owned receipt. A current
+`astrale update --check --json` result includes the resolved source revision plus every shipped
+skill's Git tree and entrypoint, so runners can retain the actual loadout rather than only
+`status: current`. `--no-skills` is the explicit opt-out.
 
 ## Commands
 

package/dist/astrale.js

@@ -2578,7 +2578,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@astrale-os/cli",
-    version: "1.0.0-beta.30",
+    version: "1.0.0-beta.32",
     description: "Astrale CLI — connect to existing Astrale kernels",
     keywords: [
       "astrale",
@@ -34087,6 +34087,20 @@ var init_auth4 = __esm(() => {
   init_auth();
 });
 
+// src/lib/credential-lifetime.ts
+function remainingCredentialLifetimeSeconds(expiresAtEpochSeconds, nowEpochSeconds = Math.ceil(Date.now() / 1000)) {
+  if (!Number.isSafeInteger(expiresAtEpochSeconds) || !Number.isSafeInteger(nowEpochSeconds)) {
+    throw new TypeError("Credential expiration and current time must be safe epoch seconds.");
+  }
+  return expiresAtEpochSeconds - nowEpochSeconds - 1;
+}
+function credentialLifetimeCovers(expiresAtEpochSeconds, minimumRemainingSeconds, nowEpochSeconds) {
+  if (!Number.isSafeInteger(minimumRemainingSeconds) || minimumRemainingSeconds < 1) {
+    throw new TypeError("Credential minimum lifetime must be a positive safe integer.");
+  }
+  return remainingCredentialLifetimeSeconds(expiresAtEpochSeconds, nowEpochSeconds) >= minimumRemainingSeconds;
+}
+
 // src/state/paths.ts
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -34141,15 +34155,19 @@ class ExchangeCredentialCache {
   constructor(path = EXCHANGE_CREDENTIALS_PATH) {
     this.path = path;
   }
-  getOrRefresh(key, refresh, now = () => Math.floor(Date.now() / 1000)) {
+  getOrRefresh(key, minimumRemainingSeconds, refresh, now = () => Math.floor(Date.now() / 1000)) {
+    if (!Number.isSafeInteger(minimumRemainingSeconds) || minimumRemainingSeconds < 1) {
+      throw new TypeError("Exchange credential minimum lifetime must be a positive safe integer.");
+    }
     const encoded = encodeKey(key);
-    const current = this.refreshing.get(encoded);
+    const pendingKey = `${encoded}\x00${minimumRemainingSeconds}`;
+    const current = this.refreshing.get(pendingKey);
     if (current !== undefined)
       return current;
-    const pending = this.getOrRefreshOnce(key, encoded, refresh, now).finally(() => {
-      this.refreshing.delete(encoded);
+    const pending = this.getOrRefreshOnce(key, encoded, minimumRemainingSeconds, refresh, now).finally(() => {
+      this.refreshing.delete(pendingKey);
     });
-    this.refreshing.set(encoded, pending);
+    this.refreshing.set(pendingKey, pending);
     return pending;
   }
   async deleteKernel(kernelIssuer) {
@@ -34167,20 +34185,20 @@ class ExchangeCredentialCache {
         delete store.entries[encoded];
     });
   }
-  async getOrRefreshOnce(key, encoded, refresh, now) {
+  async getOrRefreshOnce(key, encoded, minimumRemainingSeconds, refresh, now) {
     return withFileLock(`${this.path}.lock`, async () => {
       await ensurePrivateDirectory(this.path);
       const store = await readStore(this.path);
       const changed = scrub(store, now());
       const cached3 = store.entries[encoded];
-      if (cached3 !== undefined && validEntry(key, cached3, now())) {
+      if (cached3 !== undefined && validEntry(key, cached3, now(), minimumRemainingSeconds)) {
         if (changed)
           await writeStore(this.path, store);
         return cached3.credential;
       }
       const next = await refresh();
-      if (!validEntry(key, next, now(), 1)) {
-        throw new Error("Token exchange returned a credential inconsistent with its cache key.");
+      if (!validEntry(key, next, now(), minimumRemainingSeconds)) {
+        throw new Error("Token exchange returned a credential inconsistent with its cache key or required lifetime.");
       }
       store.entries[encoded] = Object.freeze({ ...next });
       await writeStore(this.path, store);
@@ -34239,7 +34257,7 @@ function validEntry(key, entry, now, minimumRemaining = MINIMUM_REMAINING_SECOND
       return false;
     }
     exports_grant.accept({ expr: Reflect.get(issued, "expr") });
-    return inspected.iss === key.domainIssuer && inspected.aud === key.kernelIssuer && inspected.claims.exp === entry.expiresAt && !Object.hasOwn(inspected.claims, "delegation") && proof.iss === key.kernelIssuer && proof.sub === entry.user && proof.aud === key.kernelIssuer;
+    return inspected.iss === key.domainIssuer && inspected.aud === key.kernelIssuer && inspected.claims.exp === entry.expiresAt && !Object.hasOwn(inspected.claims, "delegation") && proof.iss === key.kernelIssuer && proof.sub === entry.user && proof.aud === key.kernelIssuer && typeof proof.claims.exp === "number" && Number.isSafeInteger(proof.claims.exp) && credentialLifetimeCovers(proof.claims.exp, minimumRemaining, now);
   } catch {
     return false;
   }
@@ -38190,18 +38208,25 @@ function isSessionExpired(session, skewMs = 60000) {
     return false;
   return new Date(expiresAt).getTime() <= Date.now() + skewMs;
 }
-function accessTokenForAudience(session, audience) {
+function accessTokenForAudience(session, audience, minimumRemainingMs = 60000) {
   if (audience === undefined) {
-    return isSessionExpired(session) ? undefined : session.access_token;
+    return tokenHasMinimumLifetime(session, minimumRemainingMs) ? session.access_token : undefined;
   }
   const entry = session.tokens?.[audience];
-  if (entry && !isSessionExpired(entry))
+  if (entry && tokenHasMinimumLifetime(entry, minimumRemainingMs))
     return entry.access_token;
-  if (!isSessionExpired(session) && tokenAudienceMatches(session.access_token, audience)) {
+  if (tokenHasMinimumLifetime(session, minimumRemainingMs) && tokenAudienceMatches(session.access_token, audience)) {
     return session.access_token;
   }
   return;
 }
+function tokenHasMinimumLifetime(value2, minimumRemainingMs) {
+  const expiration = decodeTokenClaims(value2.access_token)?.exp;
+  if (typeof expiration === "number" && Number.isSafeInteger(expiration)) {
+    return credentialLifetimeCovers(expiration, Math.ceil(minimumRemainingMs / 1000));
+  }
+  return !isSessionExpired(value2, minimumRemainingMs);
+}
 function withCachedToken(tokens, accessToken, expiresAt) {
   const next = {};
   for (const [aud2, entry] of Object.entries(tokens ?? {})) {
@@ -61700,7 +61725,7 @@ async function inspectAstraleSkills(snapshot2, home, lockPath) {
     }
   }));
   if (managed.length === 0 && expectedPresence.every((present2) => !present2)) {
-    return { state: "absent", managedNames: [], managedFolders: [] };
+    return { state: "absent", sourceCurrent: false, managedNames: [], managedFolders: [] };
   }
   const folders = managed.flatMap(([name, entry]) => {
     const folder = folderName(entry);
@@ -61742,12 +61767,17 @@ async function inspectAstraleSkills(snapshot2, home, lockPath) {
       }
     }
   }
-  const exactCurrent = coherent && managed.length === snapshot2.skills.length && folders.every(({ key, folder, entry }) => {
+  const sourceCurrent = coherent && managed.length === snapshot2.skills.length && folders.every(({ key, folder, entry }) => {
     const skill = expected.get(folder);
     return key === folder && skill !== undefined && entry.ref === snapshot2.ref && actualHashes.get(folder) === skill.tree;
   });
+  const exactCurrent = sourceCurrent && folders.every(({ folder, entry }) => {
+    const skill = expected.get(folder);
+    return skill !== undefined && entry.astraleSourceRevision === snapshot2.revision && entry.astraleSourceTree === skill.tree;
+  });
   return {
     state: exactCurrent ? "current" : coherent ? "outdated" : "unhealthy",
+    sourceCurrent,
     managedNames: managed.map(([name]) => name),
     managedFolders: [...uniqueFolders]
   };
@@ -61768,6 +61798,20 @@ function installerArgs(...args) {
 async function installSnapshot(snapshot2, execute, selectedAgents) {
   return await execute("npx", installerArgs("add", `${ASTRALE_CLI_SKILL_SOURCE}#${snapshot2.ref}`, "-g", "-y", "--skill", ...snapshot2.skills.map((skill) => skill.name), ...selectedAgents.length > 0 ? ["--agent", ...selectedAgents] : []));
 }
+async function stampAstraleSource(snapshot2, lockPath) {
+  const { lock } = await readSkillLock(lockPath);
+  if (!lock)
+    throw new Error("skill installer receipt is unavailable after installation");
+  for (const skill of snapshot2.skills) {
+    const entry = lock.skills[skill.name];
+    if (!entry || !sourceOwned(entry) || entry.ref !== snapshot2.ref || entry.skillPath !== skill.path) {
+      throw new Error(`skill installer receipt is incomplete for ${skill.name}`);
+    }
+    entry.astraleSourceRevision = snapshot2.revision;
+    entry.astraleSourceTree = skill.tree;
+  }
+  await writeSkillLock(lockPath, lock);
+}
 async function selectedAgents(home, lockPath) {
   const { lock } = await readSkillLock(lockPath);
   const agents = new Set((lock?.lastSelectedAgents ?? []).filter((agent) => typeof agent === "string" && SAFE_NAME.test(agent)));
@@ -61989,8 +62033,20 @@ async function checkAstraleSkills(overrides = {}) {
   try {
     const snapshot2 = await sourceSnapshot(dependencies);
     const inspection = await inspectAstraleSkills(snapshot2, dependencies.home, dependencies.lockPath);
+    const status = inspection.state === "current" ? "current" : inspection.state === "unhealthy" ? "repair-needed" : "update-available";
     return {
-      status: inspection.state === "current" ? "current" : inspection.state === "unhealthy" ? "repair-needed" : "update-available"
+      status,
+      ...status === "current" ? {
+        source: {
+          repository: ASTRALE_CLI_SKILL_SOURCE,
+          revision: snapshot2.revision,
+          skills: snapshot2.skills.map(({ name, tree, path: path4 }) => ({
+            name,
+            tree,
+            entrypoint: path4
+          }))
+        }
+      } : {}
     };
   } catch (error52) {
     return { status: "unavailable", error: error52 instanceof Error ? error52.message : String(error52) };
@@ -62040,6 +62096,11 @@ async function syncAstraleSkills(overrides = {}) {
               throw new Error(installed.stderr || installed.stdout || "skill installer failed");
             }
             await pruneObsoleteEntries(snapshot2, dependencies.home, dependencies.lockPath, dependencies.run, knownRetired);
+            const installedInspection = await inspectAstraleSkills(snapshot2, dependencies.home, dependencies.lockPath);
+            if (!installedInspection.sourceCurrent) {
+              throw new Error("installed Astrale skills do not match the resolved source");
+            }
+            await stampAstraleSource(snapshot2, dependencies.lockPath);
             const verified = await inspectAstraleSkills(snapshot2, dependencies.home, dependencies.lockPath);
             if (verified.state !== "current") {
               throw new Error("installed Astrale skills did not pass verification");
@@ -80744,10 +80805,11 @@ function idpSessionLockPath(identityName) {
   return `${idpSessionPath(identityName)}.lock`;
 }
 async function ensureFreshSession(identityName, opts = {}) {
+  const minimumRemainingMs = minimumLifetimeMs(opts.minimumRemainingSeconds);
   const session3 = await readIdpSession(identityName);
   if (!session3)
     throw new IdpSessionMissingError(identityName);
-  if (accessTokenForAudience(session3, opts.audience))
+  if (accessTokenForAudience(session3, opts.audience, minimumRemainingMs))
     return session3;
   if (!session3.refresh_token)
     throw new IdpSessionNoRefreshTokenError(identityName);
@@ -80755,7 +80817,7 @@ async function ensureFreshSession(identityName, opts = {}) {
     const current = await readIdpSession(identityName);
     if (!current)
       throw new IdpSessionMissingError(identityName);
-    if (accessTokenForAudience(current, opts.audience))
+    if (accessTokenForAudience(current, opts.audience, minimumRemainingMs))
       return current;
     const bookmarkOrg = opts.organizationId ?? (opts.audience ? await orgIdForAudience(opts.audience) : undefined);
     const organizationId = bookmarkOrg ?? (opts.audience ? await (opts.resolveOrganizationId ?? fetchOrgHint)(opts.audience) : undefined);
@@ -80774,23 +80836,30 @@ async function ensureFreshSession(identityName, opts = {}) {
           });
         }
       }
-      const rescued = await rescueAfterInvalidGrant(identityName, current, opts.audience, e);
+      const rescued = await rescueAfterInvalidGrant(identityName, current, opts.audience, minimumRemainingMs, e);
       if (rescued)
         return rescued;
       throw e;
     }
   });
 }
-async function rescueAfterInvalidGrant(identityName, seen, audience, error52) {
+async function rescueAfterInvalidGrant(identityName, seen, audience, minimumRemainingMs, error52) {
   if (!(error52 instanceof OAuthTokenError) || error52.code !== "invalid_grant")
     return;
   const latest = await readIdpSession(identityName).catch(() => null);
   if (!latest || latest.updatedAt === seen.updatedAt)
     return;
-  if (!accessTokenForAudience(latest, audience))
+  if (!accessTokenForAudience(latest, audience, minimumRemainingMs))
     return;
   return latest;
 }
+function minimumLifetimeMs(input) {
+  const seconds = input ?? 60;
+  if (!Number.isSafeInteger(seconds) || seconds < 1 || seconds > Math.floor(Number.MAX_SAFE_INTEGER / 1000)) {
+    throw new TypeError("IdP session minimum lifetime must be a positive safe integer.");
+  }
+  return seconds * 1000;
+}
 var IdpSessionMissingError, IdpSessionNoRefreshTokenError;
 var init_idp_session = __esm(() => {
   init_state();
@@ -80835,14 +80904,14 @@ async function resolveCredential2(opts, config2, audience = config2.issuer, regi
       resolvedIdentity = identity4;
       resolvedName = identityName;
       if ((identity4.source ?? "key") === "idp")
-        return await resolveIdpAccessToken(identityName, identity4, audience);
+        return await resolveIdpAccessToken(identityName, identity4, audience, opts.minimumRemainingSeconds);
       return await signAs(identity4.subject, KEYS_DIR, resolveKeyIdentityAuthOptions(identity4, config2, audience, registrationKey));
     }
     const identity3 = await getDefault();
     resolvedIdentity = identity3;
     resolvedName = identity3.name;
     if ((identity3.source ?? "key") === "idp") {
-      return await resolveIdpAccessToken(identity3.name, identity3, audience);
+      return await resolveIdpAccessToken(identity3.name, identity3, audience, opts.minimumRemainingSeconds);
     }
     return await signAs(identity3.subject, KEYS_DIR, resolveKeyIdentityAuthOptions(identity3, config2, audience, registrationKey));
   } catch (e) {
@@ -80884,10 +80953,10 @@ function resolveKeyIdentityAuthOptions(identity3, config2, audience = config2.is
 function systemIdentityIssuer(identity3, audience, config2) {
   return identity3.subject === "system" ? audience : config2.issuer;
 }
-async function resolveIdpAccessToken(identityName, identity3, audience) {
+async function resolveIdpAccessToken(identityName, identity3, audience, minimumRemainingSeconds) {
   let resolved;
   try {
-    resolved = await ensureFreshSession(identityName, { audience });
+    resolved = await ensureFreshSession(identityName, { audience, minimumRemainingSeconds });
   } catch (e) {
     if (e instanceof IdpSessionMissingError) {
       throw new Error(`No cached IdP session for "${identityName}". Run: astrale auth login --idp ${identity3.idp ?? "<idp>"}`);
@@ -80942,9 +81011,26 @@ var init_auth7 = __esm(() => {
   };
 });
 
+// src/connection/lifetime.ts
+function invocationCredentialTtlSeconds(timeoutMs) {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) {
+    throw new TypeError("Invocation credential timeout must be a positive safe integer.");
+  }
+  return Math.max(MINIMUM_CREDENTIAL_TTL_SECONDS, Math.ceil(timeoutMs / 1000) + INVOCATION_RECEIPT_MARGIN_SECONDS);
+}
+function exchangeCredentialTtlSeconds(timeoutMs) {
+  return invocationCredentialTtlSeconds(timeoutMs) + TOKEN_EXCHANGE_SETTLEMENT_MARGIN_SECONDS;
+}
+function cachedCredentialTtlSeconds(timeoutMs) {
+  return invocationCredentialTtlSeconds(timeoutMs) + CACHE_HANDOFF_MARGIN_SECONDS;
+}
+var MINIMUM_CREDENTIAL_TTL_SECONDS = 60, INVOCATION_RECEIPT_MARGIN_SECONDS = 5, CACHE_HANDOFF_MARGIN_SECONDS = 5, TOKEN_EXCHANGE_SETTLEMENT_MARGIN_SECONDS = 15;
+
 // src/connection/exchange.ts
 function createExchangeCredentialResolver(target2, source2, fetch2, timeoutMs, cache2 = new ExchangeCredentialCache) {
   requireExchangeTransport(target2);
+  const cacheTtlSeconds = cachedCredentialTtlSeconds(timeoutMs);
+  const exchangeTtlSeconds = exchangeCredentialTtlSeconds(timeoutMs);
   return Object.freeze({
     async resolve(kernelIssuer, signal) {
       requireLive3(signal);
@@ -80956,8 +81042,8 @@ function createExchangeCredentialResolver(target2, source2, fetch2, timeoutMs, c
         domainIssuer: target2.domainIssuer,
         sourceIssuer: sourceIdentity.issuer,
         sourceSubject: sourceIdentity.subject
-      }), async () => {
-        const delegationTtlSeconds = delegationLifetime(sourceToken);
+      }), cacheTtlSeconds, async () => {
+        const delegationTtlSeconds = delegationLifetime(sourceToken, exchangeTtlSeconds);
         const client = new Client({ url: `${kernelIssuer}/invoke`, fetch: fetch2, timeoutMs });
         try {
           const authenticated3 = client.as(sourceToken);
@@ -80986,7 +81072,7 @@ function createExchangeCredentialResolver(target2, source2, fetch2, timeoutMs, c
           if (envelope === undefined)
             throw new Error("Token delegation returned no credential.");
           return {
-            ...await exchange(target2.domainIssuer, kernelIssuer, envelope, fetch2, signal),
+            ...await exchange(target2.domainIssuer, kernelIssuer, envelope, cacheTtlSeconds, fetch2, signal),
             user: user.id,
             sourceIssuer: sourceIdentity.issuer,
             sourceSubject: sourceIdentity.subject
@@ -81015,18 +81101,21 @@ function unknownFunctionOutcome(cause) {
     return false;
   return error52.reason.code === "FUNCTION_OUTCOME_UNKNOWN";
 }
-function delegationLifetime(sourceToken) {
+function delegationLifetime(sourceToken, requiredTtlSeconds) {
   const expiresAt = exports_credential.inspect(sourceToken).claims.exp;
   if (typeof expiresAt !== "number" || !Number.isSafeInteger(expiresAt)) {
     throw new AstraleError("TOKEN_EXCHANGE_SOURCE_INVALID", "The source identity credential has no valid expiration.");
   }
-  const remaining = expiresAt - Math.ceil(Date.now() / 1000) - 1;
+  const remaining = remainingCredentialLifetimeSeconds(expiresAt);
   if (!Number.isSafeInteger(remaining) || remaining < 1) {
     throw new AstraleError("TOKEN_EXCHANGE_SOURCE_EXPIRED", "The source identity credential has no lifetime available for token exchange.");
   }
-  return Math.min(EXCHANGE_TTL_SECONDS, remaining);
+  if (remaining < requiredTtlSeconds) {
+    throw new AstraleError("TOKEN_EXCHANGE_SOURCE_LIFETIME_INSUFFICIENT", "The source credential cannot cover the requested command timeout.", `Refresh the identity session or use a shorter --timeout; ${remaining} seconds remain but ${requiredTtlSeconds} are required.`);
+  }
+  return requiredTtlSeconds;
 }
-async function exchange(domainIssuer, kernelIssuer, envelope, fetch2, signal) {
+async function exchange(domainIssuer, kernelIssuer, envelope, requiredTtlSeconds, fetch2, signal) {
   const configurationUrl = new URL(exports_exchange.paths(domainIssuer).configuration, domainIssuer).toString();
   const configurationResponse = await fetchExchange(fetch2, configurationUrl, {
     method: "GET",
@@ -81083,8 +81172,31 @@ async function exchange(domainIssuer, kernelIssuer, envelope, fetch2, signal) {
   if (inspected.iss !== domainIssuer || inspected.aud !== kernelIssuer || inspected.claims.exp !== exchanged.expiresAt) {
     throw new AstraleError("TOKEN_EXCHANGE_PROTOCOL_ERROR", "Token exchange returned a credential inconsistent with the requested Domain and Kernel.");
   }
+  const remaining = effectiveExchangeLifetime(inspected, exchanged.expiresAt);
+  if (remaining < requiredTtlSeconds) {
+    throw new AstraleError("TOKEN_EXCHANGE_LIFETIME_INSUFFICIENT", "The Domain exchange credential cannot cover the requested command timeout.", `The Domain issuer returned ${Math.max(0, remaining)} seconds but ${requiredTtlSeconds} are required. Use a shorter --timeout or update the Domain execution service.`);
+  }
   return Object.freeze({ credential: exchanged.token, expiresAt: exchanged.expiresAt });
 }
+function effectiveExchangeLifetime(inspected, outerExpiresAt) {
+  let proofExpiresAt;
+  try {
+    const carried = exports_grant.acceptUnresolved(inspected.claims.grant).expr;
+    if (carried.kind !== "identity" || !("credential" in carried) || typeof carried.credential !== "string") {
+      throw new TypeError("Domain credential does not carry an identity proof.");
+    }
+    const value3 = exports_credential.inspect(carried.credential).claims.exp;
+    if (typeof value3 !== "number" || !Number.isSafeInteger(value3)) {
+      throw new TypeError("Domain credential carries an identity proof without an expiration.");
+    }
+    proofExpiresAt = value3;
+  } catch (cause) {
+    if (!(cause instanceof TypeError))
+      throw cause;
+    throw new AstraleError("TOKEN_EXCHANGE_PROTOCOL_ERROR", "Token exchange returned an invalid carried identity proof.", cause.message);
+  }
+  return remainingCredentialLifetimeSeconds(Math.min(outerExpiresAt, proofExpiresAt));
+}
 async function fetchExchange(fetch2, input, init, message2) {
   try {
     return await fetch2(input, init);
@@ -81155,14 +81267,13 @@ function requireLive3(signal) {
     return;
   throw signal.reason instanceof Error ? signal.reason : new DOMException("The operation was aborted.", "AbortError");
 }
-var EXCHANGE_TTL_SECONDS, MAXIMUM_RESPONSE_BYTES;
+var MAXIMUM_RESPONSE_BYTES;
 var init_exchange4 = __esm(() => {
   init_auth4();
   init_auth4();
   init_client3();
   init_errors2();
   init_exchange_credentials();
-  EXCHANGE_TTL_SECONDS = 5 * 60;
   MAXIMUM_RESPONSE_BYTES = 256 * 1024;
 });
 
@@ -81352,28 +81463,36 @@ var init_target2 = __esm(() => {
 });
 
 // src/connection/credential.ts
-function createConnectionCredential(expectedSourceIssuer, source2) {
+function createConnectionCredential(expectedSourceIssuer, source2, ttlSeconds = DELEGATION_TTL_SECONDS) {
+  if (!Number.isSafeInteger(ttlSeconds) || ttlSeconds < 1) {
+    throw new TypeError("Connection credential ttlSeconds must be a positive safe integer.");
+  }
   const resolveSource = source2.resolve.bind(source2);
   return Object.freeze({
-    ttlSeconds: DELEGATION_TTL_SECONDS,
+    ttlSeconds,
     async resolve(_call, signal) {
       const resolved = await resolveSource(expectedSourceIssuer, signal);
-      const ttlSeconds = sourceBoundDelegationTtl(resolved);
+      const delegatedTtlSeconds = sourceBoundDelegationTtl(resolved, ttlSeconds);
       return Object.freeze({
         credential: resolved,
-        ...ttlSeconds === undefined ? {} : { delegate: { ttlSeconds } }
+        ...delegatedTtlSeconds === undefined ? {} : { delegate: { ttlSeconds: delegatedTtlSeconds } }
       });
     }
   });
 }
-function sourceBoundDelegationTtl(input) {
+function sourceBoundDelegationTtl(input, requestedTtlSeconds) {
   try {
     const expiresAt = exports_credential.inspect(input).claims.exp;
     if (typeof expiresAt !== "number" || !Number.isSafeInteger(expiresAt))
       return;
-    const remaining = expiresAt - Math.ceil(Date.now() / 1000) - 1;
-    return Math.max(1, Math.min(DELEGATION_TTL_SECONDS, remaining));
-  } catch {
+    const remaining = remainingCredentialLifetimeSeconds(expiresAt);
+    if (remaining < requestedTtlSeconds) {
+      throw new AstraleError("CREDENTIAL_LIFETIME_INSUFFICIENT", "The selected credential cannot cover the requested command timeout.", `Use a fresh identity session or a shorter --timeout; ${Math.max(0, remaining)} seconds remain but ${requestedTtlSeconds} are required.`);
+    }
+    return Math.max(1, Math.min(requestedTtlSeconds, remaining));
+  } catch (cause) {
+    if (cause instanceof AstraleError)
+      throw cause;
     return;
   }
 }
@@ -81384,7 +81503,8 @@ function createCliCredential(target2, options, config2, fetch2 = globalThis.fetc
   const authOptions = Object.freeze({
     ...options.as === undefined ? {} : { as: options.as },
     ...options.creds === undefined ? {} : { creds: options.creds },
-    ...target2.defaultIdentity === undefined ? {} : { defaultIdentity: target2.defaultIdentity }
+    ...target2.defaultIdentity === undefined ? {} : { defaultIdentity: target2.defaultIdentity },
+    minimumRemainingSeconds: target2.domainIssuer === undefined ? invocationCredentialTtlSeconds(timeoutMs) : exchangeCredentialTtlSeconds(timeoutMs)
   });
   const source2 = {
     async resolve(audience, signal) {
@@ -81395,7 +81515,8 @@ function createCliCredential(target2, options, config2, fetch2 = globalThis.fetc
     }
   };
   const effective = target2.domainIssuer === undefined || options.creds !== undefined ? source2 : createExchangeCredentialResolver({ ...target2, domainIssuer: target2.domainIssuer }, source2, fetch2, timeoutMs);
-  return createConnectionCredential(target2.kernelIssuer, effective);
+  const ttlSeconds = invocationCredentialTtlSeconds(timeoutMs);
+  return createConnectionCredential(target2.kernelIssuer, effective, ttlSeconds);
 }
 function validateCredentialSelection(options) {
   if (options.as !== undefined && options.creds !== undefined) {
@@ -82689,7 +82810,7 @@ Behavior:
   script installs only — if Astrale was installed by another package manager this
   command refuses so that manager stays in charge; downloads are checksum-verified
   before the binary is replaced. (2) The Astrale agent skills: installs every
-  top-level skill published from astrale-os/cli main, updates healthy older
+  top-level skill published from one resolved astrale-os/cli main commit, updates healthy older
   installs, repairs inconsistent installs, and verifies the result before
   reporting success. (3) SDK deps: inside a pnpm domain
   project, proposes any @astrale-os/* dependency with a newer release and, on
@@ -83288,20 +83409,20 @@ var init_query5 = __esm(() => {
 function prepareQuery(input) {
   const limit = positiveInteger2(input.limit, "--limit", DEFAULT_LIMIT);
   if (input.ast !== undefined) {
-    if (input.sources.length > 0 || input.definition !== undefined || input.edge !== undefined || input.direction !== undefined) {
-      throw new TypeError("--ast/--file cannot be combined with sources, --definition, --edge, or --direction");
+    if (input.sources.length > 0 || input.class !== undefined || input.edge !== undefined || input.direction !== undefined) {
+      throw new TypeError("--ast/--file cannot be combined with sources, --class, --edge, or --direction");
     }
     return withPage(QueryAST.decode(input.ast), limit, input.cursor);
   }
-  if (input.sources.length === 0 && input.definition === undefined) {
-    throw new TypeError("query requires a Path source, --definition, or a canonical Query V6 document");
+  if (input.sources.length === 0 && input.class === undefined) {
+    throw new TypeError("query requires a Path source, --class, or a canonical Query V6 document");
   }
   if (input.direction !== undefined && input.edge === undefined) {
     throw new TypeError("--direction requires --edge");
   }
   const paths3 = input.sources.map((source2) => Path.parse(source2));
-  const definition2 = input.definition === undefined ? undefined : classReference(input.definition, "--definition");
-  const nodes = definition2 === undefined ? paths3 : [...paths3, definition2];
+  const selectedClass = input.class === undefined ? undefined : classReference(input.class, "--class");
+  const nodes = selectedClass === undefined ? paths3 : [...paths3, selectedClass];
   const query4 = Query.from({
     nodes
   });
@@ -83477,7 +83598,7 @@ async function queryCommand(sources2, opts) {
     input = {
       sources: sources2,
       ...ast === undefined ? {} : { ast },
-      definition: opts.definition,
+      class: opts.class,
       edge: opts.edge,
       direction: opts.direction,
       limit: opts.limit,
@@ -83547,7 +83668,7 @@ var init_query7 = __esm(() => {
     description: "Run one canonical Query V6 graph read",
     afterHelpText: `
 Behavior:
-  Positional Paths and --definition author a finite Query V6 read. --edge adds
+  Positional Paths and --class author a finite Query V6 read. --edge adds
   one exact Edge-Class expansion; --direction defaults to outgoing. --ast and
   --file accept a complete canonical astrale.graph.query/v6 document, including
   Property ordering and Node or Edge reference/value projections. --cursor resumes
@@ -83559,7 +83680,7 @@ Behavior:
 
 Examples:
   $ astrale query /:notes.example.dev:class.Note --limit 50
-  $ astrale query --definition /:notes.example.dev:class.Note --limit 50
+  $ astrale query --class /:notes.example.dev:class.Note --limit 50
   $ astrale query @note --edge /:notes.example.dev:class.references --direction outgoing --limit 25
   $ astrale query --file query.v6.json --cursor "$CURSOR"
 `,
@@ -83568,7 +83689,7 @@ Examples:
       { flags: "--ast <json>", description: "Canonical Query V6 JSON document" },
       { flags: "-f, --file <path>", description: "Read a canonical Query V6 document from a file" },
       {
-        flags: "--definition <path>",
+        flags: "--class <path>",
         description: "Select Nodes satisfying one exact Class"
       },
       { flags: "--edge <class>", description: "Expand one exact Edge Class" },