software-defence-factory 0.18.2 → 0.18.3

package/.agents/skills/factory-foundation/SKILL.md

@@ -44,7 +44,9 @@ the existing issue/task record, not a second project registry.
   manager and authenticated SSH forwarding for remote access. Record boot/login
   prerequisites and test restart recovery without starting another native turn.
   Updating or stopping an active or unknown writer must not silently interrupt
-  it. Native history and local references remain outside the package.
+  it. Native history and local references remain outside the package. Offer the
+  [optional OS release check](../../../docs/npm.md#optional-linux-release-check-timer)
+  only when selected; a metadata lookup does not install or activate a release.
 - **Proof:** start one bounded issue through the installed Inbox or CLI; inspect
   its native result, explicitly continue it, then run the project's checks and
   independent review against the exact candidate. Qualify only the authorized

package/bin/software-defence-factory.mjs

@@ -13,6 +13,7 @@ import { connectBridge, registerBridge } from '../factory/native/bridge-client.m
 import { acquireProcessLock } from '../factory/native/process-lock.mjs';
 import { manageNativeService } from '../factory/native/service.mjs';
 import { issueProvider } from '../factory/issue-provider.mjs';
+import { checkRelease } from '../factory/release-check.mjs';
 
 const root=fileURLToPath(new URL('../',import.meta.url));
 const version=JSON.parse(readFileSync(join(root,'package.json'),'utf8')).version;
@@ -36,6 +37,7 @@ Usage:
   factory continue ID --turn TURN_ID --feedback TEXT [--state PATH]
   factory interrupt ID --turn TURN_ID [--state PATH]
   factory service install|status|start|stop|restart|remove|cancel-maintenance [--state PATH] [--port PORT]
+  factory updates check --channel latest|next
   factory kit --output NEW_DIRECTORY
   factory foundation
   factory probe codex
@@ -185,6 +187,11 @@ async function command(args) {
     const {values,flags}=parse(rest,{positionals:1,allowed:['--state']});
     return online(stateFrom(flags),async bridge=>print(await bridge.request(`/api/v1/jobs/${jobID(values[0])}/resume`,{})));
   }
+  if(name==='updates') {
+    if(rest[0]!=='check')throw new Error('Use updates check --channel latest|next; release activation remains manual.');
+    const {flags}=parse(rest.slice(1),{allowed:['--channel']});
+    print(await checkRelease({version,channel:flags['--channel']}));return;
+  }
   if(name==='runtime') {
     const {flags}=parse(rest,{allowed:['--state']});
     const result={package:'software-defence-factory',version,entrypoint:root,source_checkout:existsSync(join(root,'.git')),native_state:'unknown'};

package/docs/architecture.md

@@ -13,7 +13,7 @@ The native harness remains the execution engine.
 | Small bridge | Authenticate local requests, associate issues with native sessions, refuse ambiguous or duplicate operations |
 | Codex | Agent loop, context, tools, permissions, sessions and execution history |
 | GitHub | Repository issues, templates, PRs, checks and authorized publication |
-| OS service manager | Start the pinned bridge after login/boot and supervise its process |
+| OS service manager | Start the pinned bridge after login/boot, supervise its process and optionally schedule metadata-only release checks |
 
 ## Small integration boundaries
 
@@ -38,6 +38,10 @@ These receipts prevent uncertain writes being replayed; they are not a queue or
 copy of native conversation history. There is one writer per project workspace.
 The repository's normal Git tools own commits and branches.
 
+Operator release checks read public npm metadata independently of the bridge or
+native harness. An optional OS timer only schedules that read; activation remains
+manual and must preserve native work. See [packages and releases](npm.md).
+
 ## Deployment
 
 ![Deployment](diagrams/deployment.svg)

package/docs/interfaces.md

@@ -1,7 +1,8 @@
 # Interfaces and state
 
 The Inbox and operational CLI commands use one running loopback bridge. Setup,
-login, diagnostics, method export and OS-service management are operator commands.
+login, diagnostics, method export, release checking and OS-service management
+are operator commands.
 There is no second CLI execution engine.
 
 | Intent | CLI |
@@ -40,6 +41,10 @@ Never generate a fresh ID merely to retry. Inspect `issues submissions` and use
 `issues recover` to look for the existing upstream issue; recovery does not repeat
 creation or start an agent.
 
+Release checking is an operator read: `factory updates check --channel next`
+compares public npm metadata with the executing CLI package. It does not activate
+the pinned service or invoke the harness. See [packages and releases](npm.md).
+
 ## State is observable, not invented
 
 - **Backlog**: a repository issue without execution; labels describe planning.

package/docs/migration.md

@@ -39,5 +39,4 @@ history locations, service identity and tested/untested limits. Roll back only
 with a verified idle owner and explicit old-state selection; never point the old
 runtime at native state or let both write the same workspace.
 
-Native app-server sessions live in the dedicated Codex home. Factory does not
-promise that they appear in a separate personal Codex Desktop environment.
+For native session visibility and context boundaries, see [setup](setup.md#native-codex-session-visibility).

package/docs/npm.md

@@ -15,6 +15,93 @@ for occasional use. A long-running service pins an installed package and the
 chosen Node binary; it must not run from an editable source checkout or depend on
 an npx cache being retained.
 
+## Check a selected channel
+
+```sh
+factory updates check --channel next
+```
+
+Choose `next` or `latest` explicitly. The command reads public npm metadata and
+compares it with **the CLI package executing the check**, not the pinned running
+service. Use `factory service status --state PATH` to inspect that service's
+version separately. A global npm upgrade does not activate a service release.
+
+The JSON result distinguishes `newer`, `current` and `older`. An older channel is
+never an upgrade: `latest` remains 0.17 while native 0.18 is on `next`. A different
+0.x minor line requires deliberate migration. A successful lookup exits zero,
+including when a newer release exists; unavailable, oversized or invalid metadata
+exits nonzero and means availability is unknown. Metadata is not package integrity,
+provenance, review or compatibility proof.
+
+Checking requires no Factory state, GitHub/Codex login or npm credentials. It does
+not download, install or activate a release, touch native history, or call a model.
+
+## Optional Linux release-check timer
+
+Use the OS for periodic checking. After selecting an installed release that
+supports the command, create the following **new** files in your user systemd
+directory (`$XDG_CONFIG_HOME/systemd/user`, normally `~/.config/systemd/user`).
+Inspect existing files first; do not overwrite another operator's units.
+
+`factory-release-check.service`:
+
+```ini
+[Unit]
+Description=Check the selected Factory release channel
+
+[Service]
+Type=oneshot
+ExecStart="/absolute/node" "/absolute/installed/package/bin/software-defence-factory.mjs" updates check --channel next
+TimeoutStartSec=30
+UMask=0077
+NoNewPrivileges=true
+```
+
+Replace both executable paths with the selected Node and installed package paths;
+`factory runtime` reports the package directory as `entrypoint`; append
+`/bin/software-defence-factory.mjs` for the script path and confirm
+`source_checkout` is false. A version-pinned package can be used instead of the
+global installation. Keep the chosen channel explicit. This unit
+only reads metadata; it never invokes `npm install` or `factory service restart`.
+
+`factory-release-check.timer`:
+
+```ini
+[Unit]
+Description=Daily Factory release check
+
+[Timer]
+OnCalendar=daily
+RandomizedDelaySec=15m
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+```
+
+Validate both files, run one actual lookup, inspect its result, then opt in:
+
+```sh
+systemd-analyze --user verify /absolute/path/factory-release-check.service /absolute/path/factory-release-check.timer
+systemctl --user daemon-reload
+systemctl --user start factory-release-check.service
+journalctl --user -u factory-release-check.service -n 20 --no-pager
+systemctl --user enable --now factory-release-check.timer
+systemctl --user list-timers factory-release-check.timer
+```
+
+The result and errors remain in the OS journal; this is not a dashboard alert or
+an automatic updater. The user service manager must be running; boot without login
+depends on the host's lingering and disk-unlock policy. `Persistent` catches up a
+missed calendar check, subject to the configured random delay; it does not replay
+agent work. See the [systemd timer reference](https://www.freedesktop.org/software/systemd/man/latest/systemd.timer.html).
+
+To opt out, disable and stop `factory-release-check.timer`, then remove only the
+two files you created and run `systemctl --user daemon-reload`. This does not stop
+the separate Factory Inbox service or modify native credentials and history.
+Other OS scheduling recipes require separate qualification. No Factory scheduler
+or background loop is installed by the CLI.
+
 ## Update deliberately
 
 0.18 uses `next` so old auto-updaters following `latest` do not silently activate a
@@ -27,8 +114,8 @@ then perform the supported service replacement and verify readiness/history/UI.
 Keep access/profile changes explicit. An npm upgrade alone does not change a
 pinned running service. See [migration](migration.md) and [recovery](recovery.md).
 
-Automated release checking can belong to an OS service/timer, but unattended
-activation remains deferred until safe maintenance and rollback are qualified.
+The optional timer above checks only. Unattended activation remains deferred
+until safe maintenance and rollback are qualified.
 Do not describe a manual update procedure as an automatic updater.
 
 ## Repository delivery

package/docs/recovery.md

@@ -18,6 +18,36 @@ bridge. Native Codex owns the full history. Another app-server may read persiste
 history without knowing a different process's live state; that read alone cannot
 authorize a competing writer or stopping the original process.
 
+## Native Codex login recovery
+
+For an expired or revoked login, first inspect work and the selected service:
+
+```sh
+factory status --state /absolute/private/factory-state
+factory service status --state /absolute/private/factory-state
+```
+
+Keep unknown outcomes unknown. Preserve work and reconcile ownership through the
+existing [service operation](#service-operation) rules; do not kill work to
+repair login. Once work is idle and ownership is reconciled, run:
+
+```sh
+factory login --state /absolute/private/factory-state
+factory doctor --state /absolute/private/factory-state
+```
+
+Login is native to the selected Factory Codex home; it does not replace personal
+Codex login. Doctor alone does not prove live inference or token refresh. Do not
+fall back to personal context or duplicate work if authentication remains
+unavailable. For session visibility and account boundaries, see [setup](setup.md#native-codex-session-visibility).
+
+A usage-limit response is different from an expired login. A valid account and a
+passing doctor do not establish remaining inference capacity. Preserve the
+current result and wait until native capacity is available; logging in again
+is not a remedy for exhausted usage. Continue a reconciled terminal thread
+explicitly when appropriate, rather than creating a replacement job or switching
+accounts/providers automatically.
+
 ## Service operation
 
 ```sh

package/docs/setup.md

@@ -40,6 +40,33 @@ is not a real execution or sandbox proof. Model preferences belong in the native
 configuration; access changes require deliberate requalification. Factory refuses
 an unexplained change to its pinned configuration or skill catalog.
 
+## Native Codex session visibility
+
+Codex stores configuration, authentication and history under `CODEX_HOME`
+([configuration and state locations](https://learn.chatgpt.com/docs/config-file/config-advanced#config-and-state-locations)).
+Factory uses its dedicated Codex home, so the same ChatGPT account does not
+combine local configuration or history. The supported Factory surface is the
+project Inbox and these commands through its owning bridge:
+
+```sh
+factory status --state /absolute/private/factory-state
+factory result ID --state /absolute/private/factory-state
+factory continue ID --turn TURN_ID --feedback TEXT --state /absolute/private/factory-state
+```
+
+A separate personal Codex Desktop or remote connection must not be expected to
+show Factory sessions. Desktop remote connections start their server in the
+remote user's login shell ([remote connection documentation](https://learn.chatgpt.com/docs/remote-connections#connect-to-an-ssh-host)).
+Do not copy or symlink authentication, session or database files, or enable
+personal connections to expose Factory work. A persisted native read does not
+authorize another writer. Desktop visibility or resume requires qualification
+for that deployment and is not needed for Factory's current surface.
+
+Local-home separation is not account or plan separation. API authentication and
+subscription login are distinct; do not infer plan or quota behavior from local
+state or promise automatic token refresh or indefinite coexistence. For expired
+or revoked login, follow [native Codex login recovery](recovery.md#native-codex-login-recovery).
+
 ## Start and reach the Inbox
 
 ```sh

package/factory/release-check.mjs

@@ -0,0 +1,34 @@
+const packageName='software-defence-factory';
+const versionParts=value=>{
+  if(typeof value!=='string'||!/^0\.(0|[1-9]\d{0,5})\.(0|[1-9]\d{0,5})$/.test(value))
+    throw new Error('Release metadata has an unsupported Factory version; inspect the migration manually.');
+  return value.split('.').map(Number);
+};
+
+// Read public metadata only. npm credentials, lifecycle scripts and native
+// accounts are not needed; neither the installed package nor service is changed.
+export async function checkRelease({version,channel,request=fetch}) {
+  if(!['latest','next'].includes(channel))throw new Error('Choose the release channel explicitly: --channel latest or --channel next.');
+  const installed=versionParts(version);
+  const response=await request(`https://registry.npmjs.org/${packageName}/${channel}`,{
+    headers:{Accept:'application/json'},redirect:'error',signal:AbortSignal.timeout(10000),
+  });
+  if(!response.ok)throw new Error(`Release lookup failed (HTTP ${response.status}); availability is unknown.`);
+  let size=0;const chunks=[];
+  if(!response.body)throw new Error('Release lookup returned no metadata; availability is unknown.');
+  for await (const chunk of response.body) {
+    size+=chunk.byteLength;
+    if(size>256000)throw new Error('Release metadata exceeds 256 KB; availability is unknown.');
+    chunks.push(chunk);
+  }
+  let candidate;
+  try {candidate=JSON.parse(Buffer.concat(chunks).toString('utf8'));}
+  catch {throw new Error('Release metadata is not valid JSON; availability is unknown.');}
+  if(candidate?.name!==packageName)throw new Error('Release metadata has a different package identity; availability is unknown.');
+  const available=versionParts(candidate.version);
+  const difference=available.findIndex((part,index)=>part!==installed[index]);
+  const relation=difference<0?'current':available[difference]>installed[difference]?'newer':'older';
+  return {package:packageName,channel,checked_at:new Date().toISOString(),installed_version:version,
+    available_version:candidate.version,relation,update_available:relation==='newer',
+    same_version_line:available[1]===installed[1],verification:'public metadata only',activation:'manual'};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "software-defence-factory",
-  "version": "0.18.2",
+  "version": "0.18.3",
   "description": "Factory: native Codex project Inbox, Foundation and portable ADLC method",
   "type": "module",
   "license": "MIT",

package/todo.md

@@ -4,33 +4,39 @@
 this file preserves order, not a second execution queue. Historical releases and
 retired implementation evidence remain in Git and private installation records.
 
-## Finish the native product
+## Native product
+
+[PR #120](https://github.com/arcitai/software-and-defence-factory/pull/120)
+delivered native simplification, startup, continuation, scoped Codex permissions
+and architecture in 0.18.0. [PR #122](https://github.com/arcitai/software-and-defence-factory/pull/122)
+delivered Inbox qualification in 0.18.2 and closed #37. Remaining work:
 
 - [ ] [#113](https://github.com/arcitai/software-and-defence-factory/issues/113):
-  remove the old runtime end-to-end; small CLI/bridge, automatic startup, coherent
-  documentation/diagrams and deliberate installed migration.
+  metadata-only release checks and an optional OS timer recipe are the 0.18.3
+  checking slice. Automatic download, idle activation/health and rollback remain
+  unqualified; a timer does not deliver automatic service updates.
 - [ ] [#114](https://github.com/arcitai/software-and-defence-factory/issues/114):
-  native Codex continuation, actual result/history, owning-process maintenance,
-  effective isolation and installed lifecycle qualification.
-- [ ] [#37](https://github.com/arcitai/software-and-defence-factory/issues/37):
-  preserve accepted Inbox UX and share operational actions between CLI/API/UI.
+  prove sustained native credential refresh/coexistence and qualify any separately
+  selected Desktop integration; these are not delivered.
 - [ ] [#70](https://github.com/arcitai/software-and-defence-factory/issues/70):
-  verify vision-bounded improvement in reusable method and adopting projects.
+  demonstrate a real-use, vision-bounded improvement in the method and an adopting
+  project.
+- [ ] [#6](https://github.com/arcitai/software-and-defence-factory/issues/6):
+  resume application use only when the owner resumes it.
 
-Completion requires independent review, appropriate tests, actual installed
-CLI/API/browser proof, protected PR/CI and verified adoption. Source edits or
-mock tests alone do not complete these items. Keep historical state private;
-never revive obsolete jobs automatically.
+Completion follows [CONTRIBUTING.md](CONTRIBUTING.md): independent review and
+relevant checks, with installed execution/adoption evidence where required.
+Preserve existing history; never replay obsolete work automatically.
 
 ## Later, only for a proven gap
 
 - Native harness integrations: [Claude Code #115](https://github.com/arcitai/software-and-defence-factory/issues/115),
   [Cursor #116](https://github.com/arcitai/software-and-defence-factory/issues/116),
-  [Grok #117](https://github.com/arcitai/software-and-defence-factory/issues/117).
+  [Grok #117](https://github.com/arcitai/software-and-defence-factory/issues/117),
+  deferred pending a proven need and separate qualification.
 - [#69 Local Build · Cloud Review](https://github.com/arcitai/software-and-defence-factory/issues/69):
   a qualified native recipe, not a new inference engine.
-- [#6 real-project qualification](https://github.com/arcitai/software-and-defence-factory/issues/6),
-  [#7 scoped defence case](https://github.com/arcitai/software-and-defence-factory/issues/7),
+- [#7 scoped defence case](https://github.com/arcitai/software-and-defence-factory/issues/7),
   [#50 defence method](https://github.com/arcitai/software-and-defence-factory/issues/50).
 - [#27 project accents](https://github.com/arcitai/software-and-defence-factory/issues/27),
   [#51 evidence-backed measurements](https://github.com/arcitai/software-and-defence-factory/issues/51).