@sigrun/sigrun 0.2.0 → 0.2.1

package/dist/server/auth/pipeline.js

@@ -34,8 +34,14 @@
  *     request before handlers run) + a non-empty user header; a
  *     directory miss auto-provisions (`source:"proxy"`, admin:false)
  *     unless `autoProvision:false` → 403 `user_not_provisioned`.
+ *     Every proxy rejection (401/403) emits ONE sanitized `warn` naming
+ *     the socket peer + a short reason (release-readiness Task 1, spec
+ *     §3 — never tokens, cookies, identity-header VALUES, query
+ *     strings, or the full URL; a request presenting a Bearer/cookie
+ *     credential is a token attempt and stays silent).
  *     `token`: Bearer or the `sigrun_session` cookie → `tokens.verify`;
- *     the token's user must exist in the directory, else 401.
+ *     the token's user must exist in the directory, else 401 (no log —
+ *     token failures are not proxy diagnostics).
  *  6. **Empty list** (the naive workstation path): the trimmed
  *     `X-Sigrun-User` header verbatim, `admin: true`, method `"none"`.
  */
@@ -184,6 +190,22 @@ function isPublicPath(request, ctx) {
     }
     return false;
 }
+/**
+ * The proxy-auth rejection diagnostic (release-readiness Task 1, spec §3):
+ * ONE `warn` per rejected request, naming the socket peer, the request
+ * method, a short reason, and — only when Fastify already resolved it —
+ * the ROUTE TEMPLATE (`routeOptions.url`, never the raw URL). The line
+ * must never carry API tokens, cookies, identity-header VALUES, query
+ * strings, or the full request URL; a header NAME appears only where the
+ * reason itself is "that configured header was absent/wrong" (its value
+ * never does). This is diagnostic logging, not evidence that the
+ * configured allowlist is correct.
+ */
+function warnProxyRejected(request, reason) {
+    const peer = request.socket.remoteAddress ?? "unknown";
+    const route = request.routeOptions.url;
+    console.warn(`sigrun: proxy auth rejected ${request.method} request from ${peer} (${reason})${route === undefined ? "" : ` on ${route}`}`);
+}
 /**
  * Stage 5a (proxy): resolve the forward-auth headers, or reply with the
  * rejection. The secret header is DELETED from the request before any
@@ -191,7 +213,24 @@ function isPublicPath(request, ctx) {
  */
 async function resolveProxy(request, ctx) {
     const { proxy, adminGroups } = ctx.config.auth;
+    // A request presenting a Bearer/cookie CREDENTIAL is attempting token
+    // auth (or riding the stage-3 service token), not claiming a proxy
+    // identity: when the token method is ALSO configured, suppress the
+    // rejection diagnostic — a denied credential is the token method's
+    // failure, which never logs (spec §3). The pipeline visits the proxy
+    // method FIRST for such a request (a trusted peer presenting a session
+    // without proxy headers is a legitimate client shape behind
+    // forward-auth), and a "missing secret" warn would fire even when the
+    // token then authenticates. In a PROXY-ONLY deployment the suppression
+    // does not apply: a rejected credential-bearing request there IS a
+    // proxy-method 401 and must log (spec §3 exempts token-auth failures,
+    // and no token method exists).
+    const attemptingToken = (bearerOf(request) !== undefined || sessionCookieOf(request) !== undefined) &&
+        ctx.methods.includes("token");
     if (!ipAllowed(request.socket.remoteAddress, proxy.trustedProxies)) {
+        if (!attemptingToken) {
+            warnProxyRejected(request, "untrusted proxy");
+        }
         return { status: 401 };
     }
     if (proxy.secret !== undefined && proxy.secretHeader !== undefined) {
@@ -199,12 +238,19 @@ async function resolveProxy(request, ctx) {
         const presented = headerOf(request, name);
         delete request.headers[name];
         if (presented === undefined || !timingSafeStringEqual(presented, proxy.secret)) {
+            if (!attemptingToken) {
+                warnProxyRejected(request, `missing or wrong shared secret (${proxy.secretHeader} header)`);
+            }
             return { status: 401 };
         }
     }
     const user = headerOf(request, proxy.userHeader);
-    if (user === undefined)
+    if (user === undefined) {
+        if (!attemptingToken) {
+            warnProxyRejected(request, `missing identity header (${proxy.userHeader})`);
+        }
         return { status: 401 };
+    }
     const groups = headerOf(request, proxy.groupsHeader)
         ?.split(",")
         .map((group) => group.trim())
@@ -212,12 +258,15 @@ async function resolveProxy(request, ctx) {
     const { users } = ctx.opened.identity;
     // The invalid-username case (a proxy header that can't be a directory
     // user) is a loud 403, not a 500: the proxy vouched for an identity
-    // this server can never represent.
+    // this server can never represent. The warn's reason never carries the
+    // claimed value (spec §3: no identity-header values).
     if (!/^[a-z0-9][a-z0-9._-]*$/.test(user)) {
+        warnProxyRejected(request, "unusable identity claim");
         return { status: 403, error: "invalid_username" };
     }
     const existing = users.get(user);
     if (existing === undefined && !proxy.autoProvision) {
+        warnProxyRejected(request, "untrusted identity source");
         return { status: 403, error: "user_not_provisioned" };
     }
     let record;

package/dist/server/images/cache.js

@@ -8,8 +8,8 @@
  * only).
  *
  * Layout: each entry is one file `<sha256(u)>.<variant>` beside ONE
- * `index.json` (the metadata table: type, size, added-at, last-hit,
- * pin). The index is written atomically on every mutation, so a re-open
+ * `index.json` (the metadata table: type, size, added-at, clamped
+ * max-age, last-hit, pin). The index is written atomically on every mutation, so a re-open
  * (the same cache dir, a new process) serves the prior entries.
  *
  * Eviction never deletes a file currently being STREAMED or WRITTEN
@@ -74,7 +74,8 @@ export class ImageCache {
             return;
         }
         for (const [key, entry] of Object.entries(parsed.entries)) {
-            this.entries.set(key, { ...entry, pins: 0 });
+            // Pre-max-age indexes used the original default: one hour.
+            this.entries.set(key, { ...entry, maxAge: entry.maxAge ?? 3600, pins: 0 });
         }
     }
     /** One hit, or `undefined` on a miss. `now` stamps the LRU order. */
@@ -99,12 +100,17 @@ export class ImageCache {
         entry.pins += 1;
         await this.persist();
         const stream = createReadStream(file);
+        let unpinned = false;
         const unpin = () => {
+            // Node emits close after error: one hit releases one pin.
+            if (unpinned)
+                return;
+            unpinned = true;
             entry.pins -= 1;
         };
         stream.once("close", unpin);
         stream.once("error", unpin);
-        return { type: entry.type, stream };
+        return { type: entry.type, addedAt: entry.addedAt, maxAge: entry.maxAge, stream };
     }
     /**
      * Store one fetched image. The write is staged and renamed (atomic:
@@ -112,7 +118,7 @@ export class ImageCache {
      * is pinned for the write's duration — the eviction pass a same-key
      * overwrite triggers can never remove the file mid-rename.
      */
-    async put(u, variant, type, body, now) {
+    async put(u, variant, type, body, now, maxAge = 3600) {
         await this.open();
         if (this.closed)
             return;
@@ -122,6 +128,7 @@ export class ImageCache {
             type,
             size: body.byteLength,
             addedAt: at,
+            maxAge,
             lastHit: at,
             pins: 1,
         };
@@ -180,6 +187,7 @@ export class ImageCache {
                     type: entry.type,
                     size: entry.size,
                     addedAt: entry.addedAt,
+                    maxAge: entry.maxAge,
                     lastHit: entry.lastHit,
                 },
             ])),

package/dist/server/index.js

@@ -93,8 +93,9 @@ import { resolveWebuiBundle, serveWebuiBundle, } from "./static.js";
  * then the configured methods — the resolved principal stamps
  * `SessionMeta.owner` at create/fork/import.
  * @param options.listenHost the host the server will bind (fallback
- * `"0.0.0.0"` when omitted; `serve()` passes the dual-stack `::`);
- * the pipeline's Host check and the default method list
+ * `"0.0.0.0"` when omitted; `serve()` passes its ONE resolved host —
+ * `options.host` → `SIGRUN_LISTEN_HOST` → the dual-stack `::`, serving
+ * spec §1); the pipeline's Host check and the default method list
  * (`effectiveMethods`) both derive from it.
  * @param contributedBundles the extension-contributed webui-bundle registry
  * (build-and-webui Task 6 threads it here from boot; the serve-time
@@ -299,6 +300,13 @@ export async function createServer(opened, config, contributedBundles = [], opti
         commandCatalog,
         listenHost,
         methods,
+        // The listener record (release-readiness Task 1, serving spec §2):
+        // host + port are the server construction's inputs; `families`
+        // starts EMPTY (never listened) and `serve()` fills it in place
+        // with the measured families after `app.listen` resolves — the
+        // meta route reads whichever state exists at request time, never
+        // probing itself. A hand-built test server serves intent only.
+        listener: { host: listenHost, port: config.port, families: [] },
         env,
         // U4 §13.2: the harness's settings-changed fan-out (hub publish +
         // extension onSettingsChanged + the scheduler re-arm).

package/dist/server/notifications.js

@@ -78,6 +78,10 @@ export function startNotifications(ctx) {
                 title: base.title,
                 body: base.body,
                 ...(url === undefined ? {} : { url }),
+                // The settled outcome rides ONLY run.settled events — the
+                // other variants never gain the field (the type is the union;
+                // the conditional spread keeps the wire shape exact).
+                ...(base.outcome === undefined ? {} : { outcome: base.outcome }),
             };
             for (const target of targets) {
                 // Fire-and-forget per transport call: one notifier's failure or
@@ -123,7 +127,7 @@ export function startNotifications(ctx) {
         }, recipients);
     };
     /** run.settled → the owner, gated by the live `notifications.runSettled` mode. */
-    const handleRunSettled = async (conversationId) => {
+    const handleRunSettled = async (conversationId, outcome, reason) => {
         const mode = opened.settings.read().notifications?.runSettled ?? "unwatched";
         if (mode === "never")
             return;
@@ -134,13 +138,26 @@ export function startNotifications(ctx) {
             (watchers.get(conversationId) ?? 0) > 0) {
             return;
         }
+        // Translate the EXISTING wire outcome/reason straight across (no
+        // second answer read, no inferred status). An unanswered run never
+        // titles itself "Reply ready": the reason is the run's own, with
+        // the bare status as the fallback for a reason-less settle.
+        const settledOutcome = outcome === "answered"
+            ? { status: "answered" }
+            : { status: "unanswered", reason: reason ?? "unanswered" };
+        const settledReason = reason ?? "unanswered";
         deliver({
             type: "run.settled",
             conversationId,
             jobId: undefined,
             callId: undefined,
-            title: "Reply ready",
-            body: displayName(meta, conversationId),
+            title: outcome === "answered"
+                ? "Reply ready"
+                : "Run ended without a reply",
+            body: outcome === "answered"
+                ? displayName(meta, conversationId)
+                : `${displayName(meta, conversationId)} — ${settledReason}`,
+            outcome: settledOutcome,
         }, [meta?.owner]);
     };
     /**
@@ -177,7 +194,7 @@ export function startNotifications(ctx) {
             void bus.runBounded("notifications interaction.pending", () => handleInteraction(event.conversationId, event.callId));
         }
         else if (event.type === "run.settled") {
-            void bus.runBounded("notifications run.settled", () => handleRunSettled(event.conversationId));
+            void bus.runBounded("notifications run.settled", () => handleRunSettled(event.conversationId, event.outcome, event.reason));
         }
         else if (event.type === "job.changed") {
             void bus.runBounded("notifications job.changed", () => {

package/dist/server/routes/images.js

@@ -17,9 +17,10 @@
  *   POSTed as the raw text body; the route's `bodyLimit` is the §11.1
  *   192 KiB rule (an over-limit body is Fastify's 413 `too_large`).
  *
- * Fetches go through the on-disk LRU cache (`<cacheDir>/images/`,
- * `images/cache.ts`): a hit re-serves without an upstream call, and
- * concurrent requests for one URL share ONE in-flight upstream fetch
+ * Fetches go through the on-disk LRU cache: a hit fresher than its
+ * clamped max-age re-serves without an upstream call; an older hit
+ * revalidates, and a refusal is never replaced by stale bytes.
+ * Concurrent requests for one URL share ONE in-flight upstream fetch
  * (Review Focus 4). Failures are never cached. Responses carry the
  * sniffed Content-Type, `X-Content-Type-Options: nosniff`, and
  * `Cache-Control: private, max-age=<upstream hint clamped to 1 h–7 d>`.
@@ -114,13 +115,17 @@ export function registerImageRoutes(app, ctx) {
     const inflight = new Map();
     /** Fetch one URL through the cache, sharing in-flight work. */
     async function fetchThroughCache(u, variant) {
-        const hit = await cache.get(u, variant);
-        if (hit !== undefined) {
+        const now = deps.now();
+        const hit = await cache.get(u, variant, now);
+        if (hit !== undefined && now - hit.addedAt < hit.maxAge * 1000) {
             const chunks = [];
             for await (const chunk of hit.stream)
                 chunks.push(chunk);
-            return { bytes: Buffer.concat(chunks), type: hit.type };
+            return { bytes: Buffer.concat(chunks), type: hit.type, maxAge: hit.maxAge };
         }
+        // A stale hit is never served: close its pin and revalidate.
+        if (hit !== undefined)
+            hit.stream.destroy();
         const inflightKey = `${variant}${u}`;
         const existing = inflight.get(inflightKey);
         if (existing !== undefined)
@@ -128,11 +133,13 @@ export function registerImageRoutes(app, ctx) {
         const work = (async () => {
             const fetched = await fetchImage(u, deps);
             // Cache the original variant first — `as=png` requests cache
-            // BOTH variants (the conversion reads the fetched bytes).
-            await cache.put(u, "orig", fetched.type, fetched.bytes);
+            // BOTH variants (the conversion reads the fetched bytes). The
+            // clamped hint is BOTH the response header and the cache TTL.
+            const maxAge = clampedMaxAge(fetched.maxAge);
+            await cache.put(u, "orig", fetched.type, fetched.bytes, deps.now(), maxAge);
             if (variant === "png") {
                 const converted = await toPng(fetched.bytes);
-                await cache.put(u, "png", "png", converted);
+                await cache.put(u, "png", "png", converted, deps.now(), maxAge);
                 return {
                     bytes: converted,
                     type: "png",

package/dist/server/routes/me.js

@@ -52,7 +52,7 @@ export function registerMeRoutes(app, ctx) {
         const settings = body;
         await stores.settings.set(settings);
         const { slug } = request.params;
-        opened.userServices.settingsChanged(slug, request.principal.user);
+        ctx.publishSettingsChanged({ extension: slug }, Object.keys(settings), request.principal.user);
         const response = { settings, pendingRestart: [] };
         return response;
     });

package/dist/server/routes/meta.js

@@ -39,6 +39,10 @@ export function registerMetaRoutes(app, ctx) {
             version: SIGRUN_VERSION,
             harnessVersion: HARNESS_VERSION,
             schemaVersion: SCHEMA_VERSION,
+            // The retained listener facts (release-readiness Task 1, serving
+            // spec §2): measured once at listen, projected verbatim — this
+            // route never probes (a pure synchronous projection).
+            listener: ctx.listener,
             extensions: opened.extensionOutcomes.map((outcome) => {
                 const workers = workerStatuses.get(outcome.name);
                 const surfaces = opened.extensionSurfaces.find((binding) => binding.extension === outcome.name);

package/node_modules/@sigrun/shared/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-10-28
+### Added
+- Additive listener metadata on the meta response: host, port, and
+  measured address families.
+
 ## [0.2.0] - 2026-10-27
 ### Added
 - Surface and block wire types extended for the U5/U6/U7 workstreams:

package/node_modules/@sigrun/shared/dist/views.d.ts

@@ -403,11 +403,38 @@ export type WorkerStatus = {
     readonly lastError?: string;
 };
 /** The `GET /v1/meta` payload (spec §5; the health block is Task 9e). */
+/**
+ * The measured listener facts (release-readiness Task 1, serving spec §2):
+ * captured ONCE when the listener goes live (never probed per request) and
+ * retained on the server context; `GET /v1/meta` projects them verbatim.
+ */
+export interface ListenerInfo {
+    /** The effective host string supplied to `listen` — never a resolved peer. */
+    readonly host: string;
+    /** The configured/selected port the listener bound. */
+    readonly port: number;
+    /**
+     * The address families the listener accepts, in stable `ipv4`, `ipv6`
+     * order. Literal binds report the bound socket's family; the `::`
+     * wildcard reports exactly the loopback families a startup reachability
+     * check connected on (measured, never inferred from the wildcard
+     * spelling). Empty on a server that never listened (a hand-built test
+     * server projecting intent only).
+     */
+    readonly families: readonly ("ipv4" | "ipv6")[];
+}
 export interface MetaResponse {
     /** The sigrun server's own version (the package manifest). */
     readonly version: string;
     readonly harnessVersion: string;
     readonly schemaVersion: string;
+    /**
+     * The listener facts (release-readiness Task 1, serving spec §2). A
+     * REQUIRED field on this type; OLDER SERVERS (≤0.2.0) omit it on the
+     * wire, so clients consuming it must tolerate its absence during
+     * mixed-version upgrades.
+     */
+    readonly listener: ListenerInfo;
     readonly extensions: readonly {
         readonly name: string;
         readonly status: string;

package/node_modules/@sigrun/shared/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sigrun/shared",
-	"version": "0.2.0",
+	"version": "0.2.1",
 	"description": "sigrun shared leaf package \u2014 theme tokens, turn/conversation shaping, and the channel wire types (pure leaf, zero dependencies)",
 	"type": "module",
 	"exports": {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sigrun/sigrun",
-	"version": "0.2.0",
+	"version": "0.2.1",
 	"description": "Durable personal assistant on pi-durable",
 	"type": "module",
 	"exports": {
@@ -30,7 +30,7 @@
 		"test": "vitest run",
 		"typecheck": "tsc --noEmit",
 		"build:shared": "npm --workspace @sigrun/shared run build",
-		"build": "npm run build:shared && tsc -p tsconfig.build.json && tsc -p tsconfig.extension.json && node -e \"require('node:fs').rmSync('dist/extension.js',{force:true})\"",
+		"build": "npm run build:shared && tsc -p tsconfig.build.json && tsc -p tsconfig.extension.json && node scripts/stamp-block-build.mjs && node -e \"require('node:fs').rmSync('dist/extension.js',{force:true})\"",
 		"build:webui": "npm --workspace @sigrun/webui run build",
 		"typecheck:webui": "npm --workspace @sigrun/webui run typecheck",
 		"test:e2e": "npm run build:webui && npm --workspace @sigrun/webui run test:e2e",
@@ -45,11 +45,11 @@
 		"@earendil-works/pi-tui": "^1.3.0",
 		"@fastify/static": "^10.1.7",
 		"@sigrun/ext-codemode": "0.1.1",
-		"@sigrun/ext-gateway": "0.1.1",
+		"@sigrun/ext-gateway": "0.1.2",
 		"@sigrun/ext-mcp": "0.2.1",
 		"@sigrun/ext-tool-search": "0.1.1",
 		"@sigrun/oauth": "0.1.1",
-		"@sigrun/shared": "0.2.0",
+		"@sigrun/shared": "0.2.1",
 		"croner": "^10.0.1",
 		"fastify": "^5.12.7",
 		"sharp": "^0.35.5",
@@ -59,9 +59,9 @@
 		"@sigrun/shared"
 	],
 	"optionalDependencies": {
-		"@sigrun/sandbox-linux-arm64": "0.2.0",
-		"@sigrun/sandbox-linux-x64": "0.2.0",
-		"@sigrun/tui": "0.2.0"
+		"@sigrun/sandbox-linux-arm64": "0.2.1",
+		"@sigrun/sandbox-linux-x64": "0.2.1",
+		"@sigrun/tui": "0.2.1"
 	},
 	"devDependencies": {
 		"@types/node": "^26.6.4",
@@ -90,8 +90,7 @@
 		"THIRD_PARTY_NOTICES.md",
 		"README.md",
 		"LICENSE",
-		"CHANGELOG.md",
-		"CONTEXT.md"
+		"CHANGELOG.md"
 	],
 	"allowScripts": {
 		"@google/genai@2.21.0": true,